# Agent authentication on Chattee How an agent gets access to Chattee, and exactly which credentials exist. Chattee's agent surface is one MCP server at https://chattee.ai/mcp/connect. Every request to it needs a bearer token, and a person always grants that access: by approving an OAuth consent screen, or by creating a personal access token. This file lives at `/auth.md`, the conventional discovery path from the WorkOS auth.md spec (https://github.com/workos/auth.md). Chattee does not implement that spec's agent registration; this file documents what Chattee implements and what it deliberately does not. ## Discover - A request without a token answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://chattee.ai/.well-known/oauth-protected-resource/mcp/connect"`. That challenge is how an MCP client learns to sign in. - Protected resource metadata (RFC 9728): https://chattee.ai/.well-known/oauth-protected-resource/mcp/connect - Authorization server metadata (RFC 8414): https://chattee.ai/.well-known/oauth-authorization-server - Neither document has an `agent_auth` block, because Chattee has no agentic registration. ## Pick a method - **OAuth 2.1** is for clients that can send a person to a browser: Claude.ai, ChatGPT, Cursor, Claude Code's `/mcp` sign-in. Prefer it. - **A personal access token** (`chattee_pat_…`) is for clients that send a header: Claude Code with `--header`, Codex, the Agent SDK, scripts. A person creates it on the [AI assistants page](https://chattee.ai/app/ai-assistants) with the scopes they choose and an optional expiry. It is shown once and stored hashed. The account API key is refused here, because it is neither scoped nor revocable. ## Register An OAuth client identifies itself in one of two ways: - **Client ID Metadata Document** (preferred): the `client_id` is the HTTPS URL of a metadata document the client hosts. The authorization server advertises `client_id_metadata_document_supported`. - **Dynamic client registration** (RFC 7591): `POST https://chattee.ai/backend/oauth/register`. The consent page marks a client that registered itself as unverified. There is no agentic self-registration: no `identity_endpoint`, no `anonymous`, `service_auth` or `identity_assertion` registration type, and ID-JAG assertions are not accepted. An agent cannot create a Chattee account. A person signs up at https://chattee.ai/get-started and confirms their email address first. ## Claim There is no claim ceremony and no `claim_endpoint`. A token belongs to the account of the person who approved it or created it from the start. ## Exchange Chattee supports the authorization code grant with PKCE (`S256` only) and the refresh token grant. 1. Send the person to `https://chattee.ai/backend/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `code_challenge_method=S256` and `resource=https://chattee.ai/mcp/connect`. A `resource` naming anything else is refused with `invalid_target`. 2. Exchange the code at `https://chattee.ai/backend/oauth/token` with `grant_type=authorization_code`, `code`, `code_verifier`, `redirect_uri` and `client_id`. 3. An access token lasts 60 minutes and a refresh token 30 days. Refresh with `grant_type=refresh_token`. Every refresh returns a new refresh token, so store it and stop using the old one: reusing a retired refresh token ends that connection. ## Use the access_token Send the token on every request to https://chattee.ai/mcp/connect (Streamable HTTP): ``` Authorization: Bearer ``` - It works on that endpoint only, never on `/backend/rest/*`. - The scopes decide which tools work: `projects:read`, `projects:write`, `projects:delete`, `publish`, `templates`, `files:write`, `config`, `usage:read`. Ask for the fewest that do the job. A token with only `projects:read` and `usage:read` can look at everything and change nothing. - A token grants no spending power of its own. Building needs a paid plan: a new account gets a 7-day trial with 30 credits for planning, and without a paid plan a build answers `payment_required`. Credits are bought in the builder, by a person. ## Errors - `401` with `invalid_token`: the token is missing, expired or revoked, or it is the account API key. Sign in again or use a new personal access token. - `token_inactive`: the credential stopped working during the call. A connected app signs in again; a personal access token must be replaced. - `insufficient_scope`: an ordinary tool result that names the missing scope and where to grant it. Nothing was changed. - `email_unconfirmed`: the person has not confirmed their email address yet. - `account_blocked`: the account is suspended. See the [contact page](https://chattee.ai/p/contact). - `rate_limited`: over 120 tool calls per minute, per user. Wait `retry_after_seconds`; nothing was lost. - `503` with `introspection_unavailable`: Chattee could not verify tokens for a moment. Retry after a few seconds and keep the token. - `invalid_target`: the `resource` is not https://chattee.ai/mcp/connect. ## Revocation - A person revokes any token or connected app on the [AI assistants page](https://chattee.ai/app/ai-assistants). That ends the whole connection. - A client revokes its own tokens at the RFC 7009 endpoint, `https://chattee.ai/backend/oauth/revoke`. That ends this sign-in, and other sign-ins of the same client stay valid. - There is no `events_endpoint`. The full reference is the [Chattee MCP server documentation](https://chattee.ai/docs/mcp).