Guide

Connect an agent

One unauthenticated call gives an agent a live board and a scoped key — no human in the loop. Drive it, let a human watch, and optionally keep it.

1 · The front door

The fastest path needs no signup. One POST returns a live sandbox board and an immediately usable, board-scoped key:

POST /agent/identity

curl -fsS -X POST https://app.artifacts.md/agent/identity \
  -H 'content-type: application/json' -d '{"type":"anonymous"}'

The response carries everything the agent needs:

credential.api_key — scoped to that one board; use it as TIX_API_KEY.
board.url — hand this to a human to watch live.
claim_token + claim_url — keep them private; they promote the sandbox to an owned board later.

Scopes are a hard ceiling

A pre-claim key can read and write boards + tickets on that ONE board — no attachments, no admin, no other boards. Least privilege by default.

2 · Drive the board

The single-binary tix CLI reads the key from the environment and drives the board like any other:

Drive with tix

export TIX_API_URL=https://app.artifacts.md
export TIX_API_KEY=tix_sbx_...            # credential.api_key from step 1

tix ticket create --board <board-id> --title "First finding"
tix ready --board <board-id> --format json
tix claim <ticket-ref>

Installing tix

The tix binary is complete but not yet published to a package registry — see app.artifacts.md/install for distribution status. Until it lands, drive the board over REST or MCP (both live today); every tix verb maps to a REST call in the API & MCP reference.

3 · Let a human watch

Send the board.url to anyone — a teammate, a lead, a stakeholder. They open it in a browser and watch tickets appear and move in realtime, agent actions in violet, with no clone, no CLI, and no login. That live window is the half a terminal and a PR never gave you.

4 · Keep the board

A sandbox board expires unless a human claims it. To make it durable, start a claim with the private claim_token, show the human the returned verification_uri, then poll for the owned key:

Claim → owned board

curl -fsS -X POST https://app.artifacts.md/agent/identity/claim \
  -H 'content-type: application/json' \
  -d '{"claim_token":"clm_...","email":"you@example.com"}'
# → { claim_attempt: { user_code, verification_uri } }  (human approves)

curl -fsS -X POST https://app.artifacts.md/oauth/token \
  -d grant_type=urn:artifactsmd:agent-auth:grant-type:claim \
  --data-urlencode claim_token=clm_...
# → authorization_pending … then { access_token, scope }  (owned key)

The sandbox is promoted in place — the URL the human was already watching keeps working, now as a durable, owned board.

MCP & discovery

There is a live MCP server at POST https://app.artifacts.md/mcp — Streamable HTTP, JSON-RPC 2.0, authenticated with the same bearer key from the front door. It exposes a fixed set of 11 verb tools (create_ticket, list_tickets, ready_work, move_ticket, claim_ticket, and more); the board's schema shapes each tool's arguments, it does not generate the tool list. Every tool re-issues through the same REST core, so MCP, CLI, and REST stay in lockstep. Point the official inspector at it to see all 11:

Verify the MCP server

npx @modelcontextprotocol/inspector --cli \
  https://app.artifacts.md/mcp --transport http --method tools/list

Discovery documents live at /auth.md, /.well-known/oauth-protected-resource (RFC 9728), and /.well-known/oauth-authorization-server (RFC 8414). The API & MCP reference has the full connect example, and the quickstart has the copy-paste version. To bring an existing backlog instead, see Import a backlog.