Authentication

Agent reference for token scopes, pairing, claims, recovery, and revocation.

Charming’s HTTP API uses Bearer tokens. MCP clients complete OAuth when they connect and do not handle these tokens directly. For HTTP request and response schemas, use the REST API reference.

Choose a credential

Use the smallest scope that fits the task.

Token	Scope	Use
`chrm_app_*`	One app	Returned when an agent creates an anonymous app. It can read, update, and run that app.
`chrm_user_*`	One account	Used by HTTP agents that need the user’s apps, sharing, secrets, or account settings.
`chrm_render_*`	One app at runtime	Minted by Charming for `window.charming`. Agents do not mint or manage it.

See Pricing and limits for token lifetimes.

Discovery

Do not hardcode auth metadata. Use these machine-readable sources:

OpenAPI contract for routes, schemas, security rules, and errors.
OAuth authorization server for sign-in and pairing endpoints.
OAuth protected resource for the API’s authorization server.

Anonymous app token

Create an app without an Authorization header to receive a chrm_app_* token. Keep it secret. It works only for the returned app and cannot list other apps.

An anonymous app expires unless a user claims it. Claiming the app revokes its chrm_app_* token. If an agent later uses that token, the 401 response includes a recovery block. Follow that block instead of creating a replacement app.

User token

A signed-in user can mint a chrm_user_* token with Create token. Charming returns the plaintext once. Use List tokens to inspect active tokens and Revoke token to revoke one.

An agent without a browser session should pair:

Call Start pairing.
Show the returned user_code and verification_url to the user.
Poll with Poll pairing at the returned interval.
Store the chrm_user_* token returned after approval. Charming returns it once.

The device_code is private to the agent. The user_code is safe to show to the user.

Claim an anonymous app

There are two supported flows:

Set pair: true when you create an anonymous app. Approval pairs the agent and claims the app in one flow.
If you already have a chrm_user_* token, call Claim app with the app’s chrm_app_* token as proof.

Both flows revoke the app token after claim. Use the user token for later work.

Send a token

HTTP agents send Authorization: Bearer <token>. Do not put a user or app token in a URL. Follow build-http.md for request examples.

Rendered apps use window.charming.api() instead of managing credentials. Charming attaches the render token.

Recover from auth errors

401 means the request has no valid credential. Follow error.recovery when present.
403 means the credential is valid but lacks access to the app or action. Do not retry with the same scope.
token_revoked_post_claim means an app was claimed. Pair for a user token, then retry.
token_expired includes the next auth step in error.recovery.

The OpenAPI contract defines every error field and reason.

Revoke access

Users can review and revoke agent tokens at Connected agents. HTTP agents can use List tokens and Revoke token.

Claiming an anonymous app revokes its app token. Render tokens rotate when Charming renders the app again.