Connect an agent

An agent gets its credential the way every other developer tool gets one: through the mechanism its own harness already understands. There is no custom handshake and no expiring code to paste.

The two doors

1. OAuth consent — for any harness with a Connect button: the plugin tier (Claude Code, via /connect) and every MCP connector (Claude Desktop, ChatGPT, anything speaking MCP with OAuth discovery). POST /oauth/token returns the key as access_token.
2. A dashboard key — copy it from the API keys page and set it as SUPER_ARTIFACTS_KEY in the environment the agent runs in.

Both doors mint an ordinary creator key (sa_*), and both appear as one row on the Agents page's roster.

One path per harness

Each harness persists instructions and keys its own way, so each has its own connect page — Claude Code installs the plugin, Codex appends the skill to its global AGENTS.md, Cursor writes a .mdc rule, Hermes installs a SKILL.md from a URL. The Agents page lists the exact commands, checked against each tool's own documentation.

Keys belong to one plane

There is more than one Super Artifacts deployment and they issue keys that look alike. A key from one is worthless on another, and it does not fail loudly — it publishes somewhere the person waiting is not looking. Before reusing a key it already has, an agent should ask:

curl -sS https://api.superart.page/whoami \
  -H "Authorization: Bearer $SUPER_ARTIFACTS_KEY"

A 200 naming the environment and the handle means the key belongs there. A 401 means it does not, and retrying will not change that.

Publishing before you have a key

Some planes let an agent publish one page with no account, so a person can see something before they connect anything. Ask the plane first: GET /guest on its API answers 200 when the door is open and 404 when it is not. On a 404, connect instead.

When it is open, the agent sends a multipart POST /guest/publish with a single html file (up to 5 MiB), and optionally a title, a description and a data policy. The page is public, unverified and carries a banner saying so. It holds at most 25 responses, and an address may publish three pages a day. Pages that ask for passwords or sensitive fields are refused, and a browser cannot call the endpoint.

The answer carries the page url, an expiresAt 24 hours out and a claimUrl. Open the claimUrl signed in to move the page into your workspace and keep it. Left alone, the page and its responses are deleted when it expires.

Connecting never builds

The agent connects, installs what it needs to be good at this permanently, and stops. What gets built first, and when, is your decision, made by pasting a prompt of your own choosing. Until one arrives, the correct number of artifacts to publish is zero.