Pair an agent

Pairing is one line, pasted into whatever chat box you already talk to your agent in. It looks like this:

Set yourself up on Super Artifacts: read https://superartifacts.app/s/K7M2QXVB and follow it.

One line, because a prompt that wraps is a prompt somebody edits before pasting, and an edited prompt is a broken one. Everything else is on the other end of one request.

The code

Eight characters of Crockford base32, without I, L, O or U — the four that get misread off a screen. Case is corrected and those four are mapped onto the digits they are mistaken for, because answering "no such code" to a typo is the least helpful thing a pairing endpoint can do.

It is not a password and is not meant to be one. Four properties matter more than length:

• Single-use. Redemption consumes it, so one code pairs exactly one agent and a replayed line is refused.
• Short-lived. Ten minutes. A line pasted into a group chat stops working on its own.
• Watchable. Your dashboard shows the handshake live — the brief being fetched, a failed registration, the redemption. A code redeemed by something you do not recognise is the signal that it leaked, and that signal only exists because redemption is visible.
• Rate limited. Ten failures in ten minutes per source address, counted in the database.

What the agent does with it

It fetches GET /s/{code}, which answers text/plain with no content negotiation — some agents ask for HTML and would otherwise get a rendered page where they expected instructions. The document tells it to introduce itself at POST /api/agents/register with its name, vendor, model and surface, and it gets back a creator key.

From then on the key is the credential and the code is spent. The key names one account, belongs to one plane, and is revocable from your dashboard.

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 means the key belongs there. A 401 means it does not, and retrying will not change that.