AI agents

An AI agent can start using Switchboard by itself. You don’t have to sign up for it, create an API key, or paste a secret into its prompt. Tell it to read https://app.caprid.com/auth.md, and it registers its own identity, starts a trial, and can mint Client tokens for a broadcast within a minute. If you like what it built, you claim the agent, and the trial becomes yours.

On Switchboard such an agent is an Agent, and the access token it sends is an Agent token.

How an Agent gets started

/auth.md is a set of steps written for an Agent to follow. The first part comes from WorkOS AuthKit, which Switchboard uses for sign-in. It tells the agent how to register, how to store what it gets back, and how to exchange that for a short-lived access token. The last part tells it what to do with that token on Switchboard.

You can give your Agent a prompt like this:

Read https://app.caprid.com/auth.md and follow it to get a Switchboard
trial. Then create a signing key in the trial's Namespace and mint a Client
token that can publish to room/42.

The Agent registers anonymously, so nobody has to approve anything yet. It sends the access token to the API as a bearer token:

curl https://app.caprid.com/v1/organizations \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Its first request creates its Trial Organization. The response is:

[
  {
    "id": 31,
    "name": "trial-8dfa34a41340",
    "created_at": 1793382211,
    "trial_expires_at": 1793987011
  }
]

The access token lasts about five minutes, and the Agent gets a fresh one from AuthKit whenever it needs to. Its anonymous identity lasts 3 days. For work that should outlast that, the Agent creates an API key, which the steps in /auth.md tell it to do.

What a trial can do

A Trial Organization has one Namespace, named trial- and a random tag, because nobody was there to pick a name. In it, the Agent and its API keys can:

• create, list and delete signing keys, so the Agent’s own code can mint Client tokens without calling Switchboard
• mint and verify Client tokens for Switchboard’s relays
• create, list and revoke API keys for the trial
• rename the Organization and change the Namespace’s settings

A trial can’t enroll Self-hosted relays, create or delete a Namespace, create another Organization, or manage Members and Invitations. Those routes return a 403 that says to claim the Agent, and that applies to the trial’s API keys too:

{"error": "this is a Trial Organization, which can use its Namespace's Signing keys and Client tokens and its own API keys, and nothing else until a person claims the Agent that started it"}

Starting a trial is rate-limited per address, like signup. An Agent that gets a 429 on its first request should wait and try again.

When a trial ends

A trial lapses 7 days after it starts, at its trial_expires_at. From then on its API keys get a 401, and the Agent gets a 403 saying its trial is over. Within about 10 minutes, Switchboard deletes the trial’s Namespace and its signing keys, so relays stop admitting its Client tokens. Nobody can use the Namespace’s name again.

An Agent whose trial is over can register again to start a new one, with a new Namespace. Nothing carries over from the old trial.

Claim an Agent to keep its trial

Claiming an Agent links it to you, and its trial becomes an ordinary Organization that you own. You should claim it before the trial lapses if you want to keep the Namespace, signing keys and API keys it made.

You need a Switchboard Account first. Sign up at https://app.caprid.com/app/ if you haven’t.

To claim the Agent, ask it to start a claim. It follows the claim step in /auth.md, then gives you a link:

1. Open the link and sign in with the email you use for Switchboard.
2. The page shows a code. Give that code back to the Agent.
3. The Agent finishes the claim with the code and gets a new access token.

The Agent’s next request makes you the trial’s Owner. The Organization stops being a trial, so it doesn’t lapse and its limits lift. Everything the Agent made keeps working, and the Namespace keeps its trial- name, because a Namespace’s name never changes. The Organization doesn’t count against the five you can create yourself. It shows up in your dashboard like any other.

If you claim the Agent before you’ve signed up, it gets a 403 that points you at signup, and the trial keeps running until it lapses. Sign up before then and the next request goes through. A trial that lapsed before the claim stays lapsed.

What a claimed Agent can do

A claimed Agent acts as your Account. It can do anything your dashboard session can, in every Organization you’re a Member of. Where you’re an Owner, that includes inviting and removing Members and deleting a Namespace, whose name is never reissued. You should claim only Agents you’d trust with your own sign-in.

An API key can’t manage Members or delete a Namespace, so if your Agent only needs to mint tokens, have it create an API key limited to the Namespaces it works in. See Credentials.

Switchboard keeps no list of Agents, so it can’t cut off one claimed Agent without cutting off you. To stop one, have it revoke its registration at AuthKit, which the last step of /auth.md covers, and revoke any API keys it created. Its current access token keeps working for up to five minutes after that.

For OAuth clients

Switchboard publishes OAuth protected resource metadata, so a client that already knows OAuth can find AuthKit without reading /auth.md:

curl https://app.caprid.com/.well-known/oauth-protected-resource

The response is:

{
  "resource": "https://app.caprid.com",
  "authorization_servers": ["https://auth.caprid.com"]
}

resource is always https://app.caprid.com, whichever hostname you fetched the document from. The API accepts a token AuthKit issued for Switchboard’s WorkOS client, which is what /auth.md gets you. It also accepts a token issued for exactly that resource (RFC 8707), but AuthKit doesn’t issue those: it answers invalid_target to a token request that names a resource, whatever the URL. Leave resource out and follow /auth.md. A token issued for any other resource is refused.

A 401 from the API points at the same document in its WWW-Authenticate header, as resource_metadata.