# 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.

- `cardboard:read`: inspect projects and account information.
- `cardboard:edit`: edit projects and use tools that spend credits; requires `cardboard:read` too.

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:

```sh
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:

```sh
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`:

```json
{
  "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.

Pricing: https://www.cardboard.ai/pricing Terms: https://www.cardboard.ai/terms Privacy:
https://www.cardboard.ai/privacy Help: https://www.cardboard.ai