# Capgo auth.md

> How AI agents get credentials for Capgo. Capgo implements the [auth.md agent registration protocol](https://workos.com/auth-md) (v0.6) with the `service_auth` method: you register with the user's email, the user confirms a six-digit code in the Capgo console, and you receive a Capgo API key. Registration runs on the OAuth issuer `https://capgo.app`; the MCP server and REST API live on `https://api.capgo.app`.

## Audience

AI coding agents and MCP clients (Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf, and others) that act for a Capgo user: managing apps, bundles, channels and rollouts, devices, statistics, native builds, webhooks, and push notifications.

Agents always act on behalf of a human Capgo account. Capgo has no anonymous or agent-only accounts, so `anonymous` registration is not offered, and no ID-JAG provider is trusted yet.

## Step 1: Discover

1. Fetch the protected resource metadata: [https://api.capgo.app/.well-known/oauth-protected-resource/mcp](https://api.capgo.app/.well-known/oauth-protected-resource/mcp). A `401` from `https://api.capgo.app/mcp` points there in its `WWW-Authenticate` header.
2. Fetch the authorization server metadata: [https://capgo.app/.well-known/oauth-authorization-server](https://capgo.app/.well-known/oauth-authorization-server). Its `agent_auth` block lists:
   - `skill`: this document
   - `identity_endpoint`: `https://capgo.app/agent/identity` (also published as `register_uri`, its auth.md v0.1 name)
   - `claim_endpoint`: `https://capgo.app/agent/identity/claim` (also published as `claim_uri`)
   - `identity_types_supported`: `["service_auth", "identity_assertion"]`, where `identity_assertion` only accepts `verified_email`, the pre-v0.6 form of the same email flow
   - Poll `https://capgo.app/oauth2/token` with `urn:workos:agent-auth:grant-type:claim`. It is the same token endpoint as `https://api.capgo.app/mcp/oauth/token` in the metadata; either URL works.

## Step 2: Pick a method

Use `service_auth`. Never guess the user's Capgo email from git config, environment variables or earlier sessions: ask the user to confirm the exact address. If they have no account yet, they can create one while confirming (every account starts a 14-day free trial, no credit card).

Before registering, tell the user that you will ask Capgo for access to their account with scope `capgo`, and get their consent.

## Step 3: Register

```http
POST https://capgo.app/agent/identity
Content-Type: application/json

{"type":"service_auth","login_hint":"user@example.com"}
```

Response (200):

```json
{
  "registration_id": "reg_...",
  "registration_type": "service_auth",
  "claim_url": "https://capgo.app/agent/identity/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "<timestamp, 24 hours>",
  "post_claim_scopes": ["capgo"],
  "claim": {
    "user_code": "123456",
    "expires_in": 600,
    "verification_uri": "https://console.capgo.app/agent/claim?claim_attempt_token=...",
    "interval": 5
  }
}
```

`claim_token` is returned once. Keep it in memory for the ceremony and do not persist it.

## Step 4: Claim ceremony

Show the user `verification_uri` and `user_code` in one message, for example:

> Open this link, sign in to Capgo (or sign up), and enter this code: **123456**
> https://console.capgo.app/agent/claim?claim_attempt_token=...

The code goes into the Capgo page, not back to you. On that page the user, signed in as the email you registered, enters the code and picks which organizations you may manage. Capgo then mints a dedicated API key that expires within 90 days.

Poll the token endpoint, no faster than `interval` seconds:

```http
POST https://capgo.app/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=clm_...
```

| Response | Meaning |
| --- | --- |
| `authorization_pending` | The user has not finished. Keep polling. |
| `slow_down` | Add at least 5 seconds to your interval. |
| `expired_token` | The code (10 minutes) or the registration (24 hours) expired. Get a fresh code (below), or register again. |
| `access_denied` | The user refused. Do not retry without asking them. |
| `invalid_grant` | Unknown or already used `claim_token`. Register again. |

Success (200), returned once:

```json
{ "access_token": "<Capgo API key>", "token_type": "Bearer", "scope": "capgo", "expires_in": 7776000 }
```

To get a fresh code for the same registration:

```http
POST https://capgo.app/agent/identity/claim
Content-Type: application/json

{"claim_token":"clm_...","email":"user@example.com"}
```

The response has a new `claim_attempt` block with the same fields as `claim`. `claim_expired` (410) means the registration is gone: register again.

## Step 5: Use the access token

The access token is a regular Capgo API key. There is no identity assertion or JWT-bearer refresh: when `expires_in` runs out, or a request returns `401`, register again.

| Target | Header |
| --- | --- |
| Hosted MCP `https://api.capgo.app/mcp` | `Authorization: Bearer <access_token>` |
| REST API `https://api.capgo.app` | `Authorization: Bearer <access_token>` or `x-api-key: <access_token>` |

- OpenAPI spec: [https://capgo.app/openapi.json](https://capgo.app/openapi.json)
- Keep credentials out of source control and logs.

## Revocation

Revoke the key with [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009) (200 even for unknown tokens):

```http
POST https://capgo.app/oauth2/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token
```

The user can also delete the key at any time in the Capgo console.

## Errors at the identity endpoint

| Error | What to do |
| --- | --- |
| `invalid_login_hint` | `login_hint` must be an email address. |
| `anonymous_not_enabled` | Use `service_auth`. |
| `issuer_not_enabled` | Capgo does not accept ID-JAG assertions. Use `service_auth`. |
| `invalid_claim_token`, `claimed_or_in_flight`, `claim_expired` | At the claim endpoint: register again, or keep polling an approved registration. |
| `rate_limited` (429) | Back off and retry later. |

## Other ways to connect

### OAuth 2.1 for MCP clients

Most MCP clients log in by themselves when you add `https://api.capgo.app/mcp` as a Streamable HTTP server: dynamic client registration at `https://api.capgo.app/mcp/oauth/register` (or a Client ID Metadata Document URL as `client_id`), `authorization_code` with PKCE `S256`, scope `capgo`. Setup per client: [https://capgo.app/docs/ai/mcp/](https://capgo.app/docs/ai/mcp/)

### API key created by the user

For CI and scripts: the user creates a key at [https://console.capgo.app/settings/organization/api-keys](https://console.capgo.app/settings/organization/api-keys). Keys carry RBAC roles per organization, app or channel, and can expire. Docs: [https://capgo.app/docs/public-api/api-keys/](https://capgo.app/docs/public-api/api-keys/)

### Capgo CLI

For local bundle uploads and native build requests, run `npx @capgo/cli@latest login <API key>`, then `npx @capgo/cli@latest mcp` to start the local stdio MCP server. Docs: [https://capgo.app/docs/cli/reference/mcp/](https://capgo.app/docs/cli/reference/mcp/)

## More

- Agent index: [https://capgo.app/llms.txt](https://capgo.app/llms.txt)
- Security contact: [https://capgo.app/.well-known/security.txt](https://capgo.app/.well-known/security.txt)
