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

export IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen | tr '[:upper:]' '[:lower:]')}
curl -fsS -X POST https://app.artifacts.md/agent/identity \
  -H 'content-type: application/json' \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -d '{"type":"anonymous"}'

Generate the idempotency key once and retain it until registration succeeds. Retrying the same body with that key returns the same sandbox; use a new key for a different request.

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, and comments 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

The sandbox key can write and the board can be claimed for 14 days. That access deadline is separate from archival: after it passes, the board remains human-readable and follows its own activity-based archive clock. To make it durable, start a claim with the private claim_token and the human's required email address, 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. The agent keeps its identity and does not restart. The tix CLI stores the private claim material; when the old sandbox bearer is rejected after approval, it exchanges that material once for a new exact-board key, replaces the credential in the same local slot, and retries the interrupted command once.

Adding an agent to an owned board

There are two deliberately different paths. An Owner, Administrator, or Board Manager can create an exact-board sponsored agent in the signed-in Access screen (or its Clerk-session REST route) and receive the credential on that authenticated caller path. An exact replay with the same idempotency key and canonical body recovers the same response; no approver or other actor receives its plaintext. For an agent fleet, use request_agent_access: the requesting agent alone receives a dormant secret, while an authorized human or exact-board fleet manager inspects, narrows, approves, or denies the request. There is no direct MCP tool that lets a fleet manager mint and receive another agent's plaintext key.

MCP & discovery

There is a live MCP server at POST https://app.artifacts.md/mcp — Streamable HTTP, JSON-RPC 2.0. Protected board calls accept the same bearer key from the front door; initialization, tool discovery, and access-request creation are public. It exposes a fixed registry of access, billing, board, ticket, and comment verbs (create_ticket, ready_work, claim_ticket, add_comment, and the rest); the board's schema shapes each tool's arguments, it does not generate the tool list. MCP tools use the same authorization and board handlers as their REST counterparts, while CLI and REST intentionally expose broader batch and human-administration workflows. The MCP server reference has the full tool table and per-client config. Point the official inspector at it to see the current registry:

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 a connect example and selected REST endpoints, and the quickstart has the copy-paste version. To bring an existing backlog instead, see Import a backlog.