Scoped access that stays yours

Connections are workspace tokens

Workspace owners and admins create connections on the Developers page. Each connection is a bearer token bound to one workspace and one audience: rest tokens (sw_rest_...) work only for /api/v1, and mcp tokens (sw_mcp_...) work only for /mcp.

Send the token in the Authorization header. Never put it in a URL, a query string, an import file or a browser bundle.

Authorization: Bearer sw_rest_...

Scopes narrow what your role allows

A new connection starts with the read-only defaults: workspaces:read, catalog:read and worlds:read. Add only what the job needs, for example worlds:write to edit drafts or worlds:publish to publish. GET /me needs account:read.

A scope never grants more than the person who created the token can do, and that role is read again on every request. Ids from another workspace answer 404, so a token cannot discover what it may not see.

Sensitive scopes are opt-in

Scopes that reach subscriber addresses, visitor messages, billing, deletion, DNS writes, spending, team changes or webhooks are never pre-ticked. Adding one asks you to sign in again first. Their MCP tools stay hidden until the token has them.

Some actions are never available to a token at all: deciding an approval, deleting or restoring casas and accounts (these need a fresh first-party sign-in and answer 403 reauthentication_required), and data exports.

Expiry, rotation and revocation

• Tokens expire after 30 days by default and after 90 days at most.
• Only a hash is stored, so a lost token cannot be shown again. Create a new connection instead.
• To rotate, create a new connection, switch your client to it, then revoke the old one. Revocation applies on the next request, including work an agent had queued.

Errors to expect

• 401: the token is missing, unknown, expired, revoked or meant for the other audience.
• 403 insufficient_scope: the token lacks a permission. context.required_scope names it and the response carries a WWW-Authenticate header.
• 404: the resource does not exist in this token’s workspace.

OAuth is not available yet

Agent clients that only support OAuth sign-in cannot connect yet. /.well-known/oauth-protected-resource/mcp lists no authorization server for that reason. Use a connection token in the client’s header settings instead.