# Sozee agent authentication

How an AI agent obtains credentials for Sozee. This follows the section layout of the auth.md convention (https://github.com/workos/auth.md). Sozee's protected resource is its MCP server at `https://mcp.sozee.ai/mcp`. There is no separate REST API.

Short version: Sozee supports user-delegated OAuth 2.1 only. A person signs in to their own Sozee account and approves the agent. Sozee does not issue credentials to an agent on its own, so the `agent_auth` methods of the convention (`anonymous`, `identity_assertion`, `service_auth`) are not supported today, and there is no `identity_endpoint`.

## Discover

1. Call `https://mcp.sozee.ai/mcp` without a token. The server answers `401` with a `WWW-Authenticate: Bearer resource_metadata="..."` header.
2. Fetch the protected resource metadata (RFC 9728): `https://mcp.sozee.ai/.well-known/oauth-protected-resource`. It names the resource, the authorization server and `scopes_supported`.
3. Fetch the authorization server metadata (RFC 8414): `https://clerk.sozee.ai/.well-known/oauth-authorization-server`. It lists the authorization, token, registration and revocation endpoints.

The authorization server metadata carries no `agent_auth` block, because none of those methods is offered.

## Pick a method

One method is available: the OAuth 2.1 authorization code grant with PKCE (`S256`), with the user present in a browser. The authorization server also supports the refresh token grant.

Not available: `anonymous` access, `identity_assertion` (including ID-JAG, `urn:ietf:params:oauth:token-type:id-jag`) and `service_auth`. An agent with no user to sign in cannot get a token.

## Register

Clients register themselves. The authorization server supports dynamic client registration at the `registration_endpoint` in its metadata, and client ID metadata documents. Public clients use `token_endpoint_auth_method: none` with PKCE. No manual approval or API key is involved.

## Claim

Nothing to claim. The token belongs to the user who signed in, and it acts on that user's Sozee account: their characters, credits and connected social accounts. A user without an account creates one at https://app.sozee.ai/sign-up.

## Exchange

Send the user to the `authorization_endpoint` with `response_type=code`, your `client_id`, `redirect_uri`, a `code_challenge` and the `resource` parameter set to `https://mcp.sozee.ai/mcp`. Exchange the returned code at the `token_endpoint` with the `code_verifier`. Scopes the resource accepts: `openid`, `profile`, `email`, `user:org:read`.

## Use the access_token

Send it on every MCP request:

```
POST https://mcp.sozee.ai/mcp
Authorization: Bearer <access_token>
```

The token is accepted in the header only. It is never read from the query string.

## Errors

- `401` with `WWW-Authenticate: Bearer resource_metadata="..."`: the token is missing, expired or not valid for this resource. Refresh it, or run the flow again.
- A tool that answers with a plan or credits refusal: the account's plan does not include that flow, or the balance is too low. Tell the user. A new token will not change it.

## Revocation

Revoke a token at the `revocation_endpoint` in the authorization server metadata. A user can also sign out or remove the connection in their AI client. For account or security help, email support@sozee.ai.