auth.md

Cardboard authentication for agents

Cardboard edits video through its MCP server and the cb CLI. Authentication uses Clerk OAuth and requires the user's approval.

MCP clients

Connect to https://mcp.cardboard.ai/mcp and use the OAuth flow advertised by https://mcp.cardboard.ai/.well-known/oauth-protected-resource/mcp.

Let the host complete OAuth consent. MCP tokens are for the MCP resource, not /api/v1.

CLI and remote terminals

Install the CLI

The public standalone installer supports macOS on Apple silicon (arm64). Intel Macs, Linux, and Windows have no public standalone CLI release yet. Agents on those platforms can use the remote MCP server above; its managed sandboxes already include cb.

If cb is already available, continue to sign-in below. Otherwise, ask the user to approve installing it on their Mac, then run this in a shell on that Mac:

curl -fsSL https://assets.cardboard.ai/cb/install.sh | sh

The installer downloads about 200 MB into ~/.cardboard, verifies release checksums and Cardboard's code signatures, and links cb and cardboard into ~/.local/bin. It needs no Node installation or admin password; run it as the user, without sudo. It prints the installed version on success. If ~/.local/bin is outside PATH, invoke ~/.cardboard/bin/cb directly. Use cb update for subsequent updates.

For Codex, use this installer command instead to also register cb mcp as the local cardboard MCP server:

curl -fsSL https://assets.cardboard.ai/cb/install.sh | sh -s -- --codex

Start a new Codex chat after installation to load that server. If your shell runs in a cloud container rather than on the user's Mac, use remote MCP instead of running the Mac installer there.

Sign in with the CLI

Run cb auth status --json to check authentication. Run cb auth login for local browser sign-in, or cb auth login --device from SSH, containers, or remote agent environments. Show the user the verification URL and code printed by the CLI. They open it in their own browser, sign in or sign up, and approve access. The CLI waits and stores the resulting credentials privately for subsequent commands. Never ask the user to share their password, access token, refresh token, or private device code in chat. cb auth logout removes local credentials.

CLI sign-in uses Clerk OAuth credentials for /api/v1. The service_auth registration below issues credentials for remote MCP only; use cb auth login to authenticate the CLI separately.

Clients implementing the device flow directly first fetch https://www.cardboard.ai/api/v1/auth/config. Use its clientId, deviceAuthorizationEndpoint, tokenEndpoint, and scopes. If no device endpoint is advertised, device sign-in is unavailable in that environment; use browser OAuth instead. POST form-encoded client_id and scope to the device endpoint. Display the returned verification_uri and user_code; keep device_code private. Poll the token endpoint with client_id, grant_type=urn:ietf:params:oauth:grant-type:device_code, and device_code, respecting interval and expires_in. Continue on authorization_pending, increase the interval by at least five seconds on slow_down, and stop on denial, expiry, or other errors. Store tokens securely and send API access tokens as Authorization: Bearer .... The CLI requests openid profile email offline_access and refreshes its saved credentials automatically.

Registration and usage

For user-claimed auth.md registration, first fetch https://mcp.cardboard.ai/.well-known/oauth-protected-resource. Fetch /.well-known/oauth-authorization-server on each advertised authorization_servers origin and select the server whose agent_auth.identity_types_supported contains service_auth. Cardboard's registration authorization server is https://www.cardboard.ai, with metadata at https://www.cardboard.ai/.well-known/oauth-authorization-server and agent_auth.skill pointing back to this document. If no server advertises service_auth, use the Clerk OAuth flows above.

POST JSON to the advertised identity_endpoint:

{
  "type": "service_auth",
  "login_hint": "the-users-email@example.com",
  "scopes": ["cardboard:read", "cardboard:edit"]
}

Ask the user which email to use; do not guess their identity. Omit edit scope for read-only access. The default is cardboard:read. Show the returned claim.verification_uri and six-digit claim.user_code to the user. They sign in or sign up with Clerk, verify that email, enter the code, and explicitly approve the listed access. No credentials are available before approval. Do not open or complete the approval page on the user's behalf.

Keep claim_token and the verification URL private. Poll the advertised token_endpoint using a form-encoded POST with grant_type=urn:workos:agent-auth:grant-type:claim and claim_token. Wait at least claim.interval seconds between polls. Continue on authorization_pending, increase the interval by at least five seconds on slow_down, and stop on access_denied or expired_token. Claims expire after ten minutes; start a new registration to retry.

On approval the response includes a short-lived access_token and a service-signed identity_assertion. Use the access token as a bearer at the MCP resource advertised by Protected Resource Metadata. These tokens do not work at /api/v1 or the /claude MCP resource. When the access token expires, POST grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, assertion=<identity_assertion>, and resource=<the-advertised-MCP-resource> to the token endpoint. The assertion is reusable until its expiry (at most 30 days); no refresh token is issued. Never share either credential in chat.

Revoke one access token with a form-encoded token=<access_token>&token_type_hint=access_token POST to the advertised revocation_endpoint. This does not revoke the assertion. Users can revoke the entire authorization and all its credentials at https://www.cardboard.ai/auth/agents. Reauthorization requires a new approval.

Anonymous registration and provider-attested identity assertions are not supported. Existing account permissions, plan limits, and credit charges apply to agent activity. Get the user's authorization before using tools that spend credits.