# Actual AI Agent Authentication

Actual AI supports browser-based OAuth for the CLI and MCP-backed agent workflows. Agents should discover authentication from this file, from `/.well-known/oauth-protected-resource`, or from `WWW-Authenticate: Bearer resource_metadata="https://actual.ai/.well-known/oauth-protected-resource"` on protected API probes.

## Discover

Read the protected resource metadata at:

- `https://actual.ai/.well-known/oauth-protected-resource`

Read authorization server metadata at:

- `https://actual.ai/.well-known/oauth-authorization-server`

The same metadata is linked from `llms.txt`, `llms-full.txt`, `/.well-known/agent.json`, and the HTTP `Link` header.

## Pick a method

For human-approved agent access, use OAuth 2.0 Authorization Code with PKCE. Device and no-browser flows are handled by the Actual CLI for SSH or headless environments.

For WorkOS auth.md-compatible agent auth, use the `agent_auth` metadata block. Supported identity types are `anonymous` for discovery-only requests and `identity_assertion` for user- or organization-bound access.

## Register

Agent registration discovery is advertised as:

- `register_uri: https://actual.ai/agent-auth/register`

Agents should request only the scopes they need. Current scope names are:

- `status:read` for public status checks.
- `adr:read` for reading approved ADR context.
- `adr:query` for asking Advisor questions.
- `adr:review` for architecture-aware code review.
- `repo:read` for repository metadata needed by analysis workflows.

## Claim

Use `claim_uri: https://actual.ai/agent-auth/claim` to exchange an approved identity assertion. When using `identity_assertion`, accepted assertion types include `id-jag` and `urn:ietf:params:oauth:token-type:id_token`.

## Use the credential

Send credentials as:

```http
Authorization: Bearer <access_token>
```

Protected Actual AI resources return structured JSON errors. A missing or invalid token returns `401` with a `WWW-Authenticate` challenge that points back to protected-resource metadata.

## Errors

Agents should handle `invalid_token`, `insufficient_scope`, `rate_limited`, and `temporarily_unavailable`. Retry only when a `Retry-After` header or explicit error hint says retrying is appropriate.

## Revocation

Use `revocation_uri: https://actual.ai/agent-auth/revoke` to revoke a credential. Users can also revoke CLI and MCP credentials from the Actual AI app.

## agent_auth

```json
{
  "agent_auth": {
    "skill": "https://actual.ai/auth.md",
    "register_uri": "https://actual.ai/agent-auth/register",
    "claim_uri": "https://actual.ai/agent-auth/claim",
    "revocation_uri": "https://actual.ai/agent-auth/revoke",
    "identity_types_supported": ["anonymous", "identity_assertion"],
    "anonymous": {
      "credential_types_supported": ["none", "oauth2"]
    },
    "identity_assertion": {
      "assertion_types_supported": ["id-jag", "urn:ietf:params:oauth:token-type:id_token"],
      "credential_types_supported": ["oauth2"]
    }
  }
}
```