Mux
Switchboard Account API 1
Section titled “Switchboard Account API 1”Manage your Organizations on Switchboard: their Namespaces, the Signing keys and Client tokens for each Namespace, their API keys, and the Self-hosted relays they enroll.
An Organization is a customer, and a Namespace is a path root it owns,
like an S3 bucket. Routes name what they act on. Everything that serves
the whole Organization (API keys, Nodes, enrollments) is under
/v1/organizations/{id}. Everything inside one Namespace (Signing keys,
Client tokens, its settings) is under /v1/namespaces/{namespace}. That
path needs no Organization, because Namespace names are unique.
Every request except signup, login, logout and the health check needs a
credential. Send an API key as Authorization: Bearer sb_.... An API key
belongs to one Organization and reaches only that Organization and its
Namespaces. You can limit a key to some of those Namespaces, so a staging
CI key can’t read prod’s Signing keys. A limited key gets a 403 outside
its Namespaces and on every /v1/organizations/{id} route. The dashboard
uses a session cookie instead, which reaches every Organization the
signed-in person is a Member of. Anything you can’t reach is a 404,
whether or not it exists.
On a server that logs people in through WorkOS, such as
app.caprid.com, there are no passwords. You sign in at /app/ in
a browser, and create API keys there for your scripts. On that server,
POST /v1/login returns 410, and POST /v1/signup works only as the
last step of signing in through the browser.
An AI agent can use the API without you creating an API key for it, on
a server set up for Agents. The Agent registers with WorkOS AuthKit, by
following the steps at /auth.md, and sends the access token AuthKit
gives it, its Agent token, as Authorization: Bearer .... Once you claim the Agent at AuthKit, it acts
as your Account, so it can do anything your dashboard session can,
including creating API keys for itself. If you haven’t signed up yet, the
Agent gets a 403 on every route until you do.
An Agent nobody has claimed can start right away. Its first request gives
it a Trial Organization with one Namespace, named trial- and a random
tag, so it can create Signing keys, mint Client tokens for Platform
relays, and create API keys for itself, with no person involved. A trial
has no Members. It can’t enroll Self-hosted relays, create or delete a
Namespace, create an Organization, or manage Members and Invitations, and
those routes return 403 to the Agent and to the trial’s API keys alike.
Starting trials is rate-limited per address, like signup, so an Agent’s
first request can return 429.
The 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 that says the
trial is over. Within about 10 minutes Switchboard deletes the trial’s
Namespace and its Signing keys, so relays stop admitting its Client
tokens, and nobody can take the name again.
Claim the Agent before then to keep what it made. Its first request after you claim it makes you the trial’s Owner, and the Organization stops being a trial. It no longer lapses, its limits lift, and its Namespace, Signing keys and API keys keep working. It doesn’t count against the Organizations you may create. If you claim the Agent before you sign up, the trial waits for you until it lapses. A trial that lapsed before the claim stays lapsed.
Paths you send (path, publish, subscribe) are relative to the
Namespace, so path: "room/42" sent to /v1/namespaces/acme/tokens is
acme/room/42.
The routes from before Organizations (/v1/keys, /v1/tokens,
/v1/enrollments, /v1/nodes, /v1/account/api-keys, and PATCH /v1/account) still work with an API key, acting in its Organization.
/v1/keys, /v1/tokens and PATCH /v1/account work only while the key
reaches exactly one Namespace: its Organization’s only one, or the only
one in its limit. The others act on the whole Organization, so a limited
key gets a 403. With a session, they return 400 and name the route to use.
Request bodies are JSON. An empty body is the same as {}, and unknown
fields are ignored. Times are Unix seconds. Errors are always
{"error": "..."}, with a message meant for a person to read.
Authentication
Section titled “Authentication”apiKey
Section titled “apiKey”An API key, sb_.... Create one in the dashboard or with POST /v1/organizations/{id}/api-keys.
Security scheme type: http
session
Section titled “session”The dashboard’s session cookie, set by signup and login. Only accepted
on same-origin requests, so it can’t be used from another site. Over
HTTPS it’s named __Host-switchboard_session, which browsers accept
only from this host, so no other host under the same domain can plant
one. A server you run over plain HTTP names it switchboard_session.
Security scheme type: apiKey
Cookie parameter name: __Host-switchboard_session
agentToken
Section titled “agentToken”The AuthKit access token an AI agent sends, on a server set up for
Agents. The Agent registers with this server’s WorkOS AuthKit domain
and exchanges its assertion for the token, which lasts about five
minutes. Until a person claims the Agent, the token acts in the
Agent’s Trial Organization. Once a person claims it, the token acts as
that person’s Account, with everything their session can do, and its
first request makes them the trial’s Owner. The server
checks the token’s signature against AuthKit’s published keys, and
that AuthKit issued it for this server’s WorkOS client or for this
server as a resource, the resource in
/.well-known/oauth-protected-resource.
Security scheme type: http
Bearer format: JWT