# Authenticating to Cork

<!--
title: "Authenticating to Cork"
description: "How an agent gets credentials to Cork on its own: register at the identity endpoint (an anonymous sandbox, service_auth with the person's email, or a provider's ID-JAG), the claim ceremony a person completes, OAuth 2.1 with PKCE, bearer tokens, errors and revocation."
canonical: "https://corkcli.com/auth.md"
last_updated: "2026-11-14"
-->

Agents get credentials to Cork on their own: there is no API key to request, no form and no sales call. There are two ways in, both self-serve:

- **Register at the identity endpoint**, `POST https://mcp.corkcli.com/agent/identity` (the agent-auth profile, [auth.md for agents](https://github.com/workos/auth.md)), and claim at the claim endpoint, `POST https://mcp.corkcli.com/agent/identity/claim`. An anonymous agent gets a sandbox at once, with no account and no key to ask for. An agent that knows its person's email gets a code for them to type. Either becomes a person's agent the same way: that person signs in to Cork and types the code.
- **OAuth 2.1 with PKCE**, which every MCP client runs when you add `https://mcp.corkcli.com`.

Every token with real access belongs to a person who signed in to Cork: it works in their workspaces, and its agent hours count on their plan (Free is 10 a month). An agent nobody has claimed gets its sandbox and nothing more. The sections below follow the profile's walkthrough: Discover, Pick a method, Register, Claim, Exchange, Use the access_token, Errors, Revocation. To try Cork with no credential at all, see the [sandbox](https://corkcli.com/docs/sandbox.md).

## Discover

The MCP server at `https://mcp.corkcli.com` and the REST API at `https://api.corkcli.com` are OAuth 2.0 protected resources.

1. Call either without a token. The MCP server answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://mcp.corkcli.com/.well-known/oauth-protected-resource"`.
2. The protected-resource metadata (`oauth-protected-resource`, RFC 9728) at `https://mcp.corkcli.com/.well-known/oauth-protected-resource` names the resource, the authorization server and the scope, `collide`.
3. The authorization server metadata (`oauth-authorization-server`, RFC 8414) at `https://mcp.corkcli.com/.well-known/oauth-authorization-server` lists `authorization_endpoint`, `token_endpoint` `https://mcp.corkcli.com/token`, `registration_endpoint`, the grant types `authorization_code`, `refresh_token`, `urn:ietf:params:oauth:grant-type:jwt-bearer` and `urn:workos:agent-auth:grant-type:claim`, PKCE `S256`, token endpoint auth method `none` (public clients) and `client_id_metadata_document_supported: true`. Read it in full: it ends with an `agent_auth` block.
4. The `agent_auth` block:
   - `skill`: this file.
   - `identity_endpoint`: `https://mcp.corkcli.com/agent/identity`; `claim_endpoint`: `https://mcp.corkcli.com/agent/identity/claim`.
   - `identity_types_supported`: `["anonymous", "service_auth"]`. `identity_assertion` is added, with `identity_assertion.assertion_types_supported: ["urn:ietf:params:oauth:token-type:id-jag"]`, once an agent provider is on Cork's trust list. None is today.
   - `pre_claim_scopes` (`sandbox`), `post_claim_scopes` (`collide`), and `sandbox`, the sandbox's docs.
   - `oauth`: the other way in, an OAuth client a person approves: `registration` (`client_id_metadata_document` or `dynamic_client_registration`, the `registration_endpoint` and a `template`) and `authorization` (the endpoints, `S256`, auth method `none`, scope `collide`).
5. Plans, the sandbox and the same URLs, with no sign-in: `https://api.corkcli.com/api/v1/plans`.

```bash
curl -s https://mcp.corkcli.com/.well-known/oauth-authorization-server | jq .agent_auth
```

## Pick a method

- **`anonymous`**: no person yet, or the agent wants to try Cork first. A sandbox at once; claim it later with the person's email.
- **`service_auth`**: the agent knows its person's email (the `login_hint`). They sign in to Cork as that email and type the code the agent shows them. Cork never sends the code: it comes from the agent.
- **`identity_assertion`** (an ID-JAG from the agent's provider): not open yet. Cork trusts an issuer only when it is on the trust list, and no agent provider publishes ID-JAG issuers and keys for apps today; until one does, a request answers `identity_assertion_not_enabled`. Once one is listed, the person links their provider identity to their Cork account once, with the same code, and from then on their agent is let in with no one in the loop.
- **OAuth 2.1 authorization code with PKCE**: an MCP client, or any agent that can open a browser for its person (Claude Code, Codex, Cursor, Gemini CLI, claude.ai, ChatGPT, your own client). Every listed client runs it when you add the server; `codex mcp login cork` starts it for Codex.
- **A machine running the hooks**: the installer (`curl -fsSL https://corkcli.com/install.sh | sh` or `npx corkcli`) works with no account on one machine. `cork login` links the machine to an account through the OAuth flow in the browser.

There are no static API keys and no client secrets: every client is public, and every credential is minted for a registration or a signed-in person.

## Register

### anonymous

```bash
curl -s https://mcp.corkcli.com/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type": "anonymous"}'
```

`200` with `registration_id`, `registration_type`, `identity_assertion` and `assertion_expires`, `pre_claim_scopes` (`["sandbox"]`), `claim_url` (the claim endpoint), `claim_token` and `claim_token_expires` (24 hours), `post_claim_scopes` (`["collide"]`), and `sandbox` (the token endpoint, the MCP address, `"repos": "sandbox/<name>"`, `"agent_hours": 0`, `"tool_calls": 1000`, `"calls_per_second": 2`).

Exchange the `identity_assertion` for a sandbox token (Exchange, below). The sandbox is the registration's own workspace: repos named `sandbox/<name>` only, the MCP server's tools that read and write them (not `setup`, `connect_agents` or `send_agent_message`), no agent hours, 1,000 tool calls at most and 2 a second, nothing on the hooks' routes or the REST API. It is deleted 24 hours on unless it is claimed.

### service_auth

```bash
curl -s https://mcp.corkcli.com/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type": "service_auth", "login_hint": "person@example.com"}'
```

`200` with `registration_id`, `registration_type`, `claim_url`, `claim_token`, `claim_token_expires` (an hour), `post_claim_scopes`, and `claim`: `user_code` (six digits), `verification_uri`, `expires_in` (600) and `interval` (5). No token comes before the claim. A `login_hint` that is not an email address answers `400 invalid_login_hint`.

### identity_assertion

```bash
curl -s https://mcp.corkcli.com/agent/identity \
  -H "Content-Type: application/json" \
  -d '{"type": "identity_assertion", "assertion_type": "urn:ietf:params:oauth:token-type:id-jag", "assertion": "<ID-JAG>"}'
```

Cork checks that `typ` is `oauth-id-jag+jwt`; that `iss` is exactly an issuer on the trust list; the signature verifies against that issuer's JWKS (its configured URL, never one the token names) with one of its algorithms, asymmetric only; `aud` is this authorization server, alone; `exp` has not passed and `iat` is present, with a life of ten minutes at most and a minute of clock skew; `jti` and `sub` are present, and the `jti` was never used before; `client_id` is present and one the issuer signs for; `email` is present with `email_verified: true`; `auth_time` is within the hour.

- A provider identity the person has linked: `200` with `registration_id`, `registration_type`, `identity_assertion`, `assertion_expires` and `scopes` (`["collide"]`).
- Never linked: `401 interaction_required` (`WWW-Authenticate: AgentAuth error="interaction_required"`), with the same claim fields as `service_auth`, for the asserted email.

### OAuth clients

Either identify the client with a Client ID Metadata Document (an https URL as `client_id`, no registration step), or register dynamically (RFC 7591):

```bash
curl -s https://mcp.corkcli.com/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "my-agent", "redirect_uris": ["http://127.0.0.1:8765/callback"]}'
```

The answer (`201`) carries a `client_id`, with `token_endpoint_auth_method: "none"`. `redirect_uris` must be https, http to a loopback address (any port, RFC 8252), or an app's own scheme; at most 10. Registrations are limited per address per hour.

### Registration template

The `agent_auth.oauth.registration.template` in the metadata is a body `/register` accepts as it stands; only `client_name` and `redirect_uris` are read:

```json
{"client_name": "my-agent", "redirect_uris": ["http://127.0.0.1/callback"]}
```

A registered loopback redirect matches any port, so listen on whichever port is free and send `redirect_uri=http://127.0.0.1:<port>/callback`.

### Client ID Metadata Document

Or skip registration: use an https URL as your `client_id`, serving this JSON at that URL. Cork fetches it (at most hourly) and requires its `client_id` to equal the URL:

```json
{"client_id": "https://agent.example.com/oauth/client.json", "client_name": "my-agent", "redirect_uris": ["http://127.0.0.1/callback"]}
```

### Rate limits

Registrations of type `anonymous` and `service_auth` together: 5 an hour from one address, 100 an hour overall. `identity_assertion`: 60 an hour from one address. Claims started: 20 an hour from one address. Past a limit: `429 rate_limited`.

## Claim

How an agent becomes a person's:

1. An `anonymous` registration starts its claim with the person's email:

   ```bash
   curl -s https://mcp.corkcli.com/agent/identity/claim \
     -H "Content-Type: application/json" \
     -d '{"claim_token": "clm_...", "email": "person@example.com"}'
   ```

   `200` with `registration_id`, `status` (`initiated`), `expires_at` and `claim_attempt`: `user_code`, `verification_uri`, `expires_in` and `interval`. A `service_auth` or `identity_assertion` registration got its code at registration; it may start a new one the same way, for the same email only. Each new code replaces the last.
2. Show the person the link and the code. They open `verification_uri` (a page on corkcli.com), sign in as that email, or sign up (a new account lands on Free), type the code and tick the workspaces the agent may use. Signed in as any other email, the page refuses. A code lasts 10 minutes, five wrong codes lock it, and a registration may start 10 codes.
3. Poll the token endpoint every `interval` seconds with `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=clm_...` (Exchange, below).

On the claim, everything the registration held before is revoked at once: its sandbox tokens, its pre-claim assertion, and its sandbox workspace with what was in it.

One related step: a machine can be linked without a browser on it. When a signed-in agent calls the MCP tool `setup`, the answer includes a one-time code (valid 15 minutes), and `cork install --claim CODE` on that machine makes the code its link to the same account.

## Exchange

All at `https://mcp.corkcli.com/token`, form-encoded. Answers carry `Cache-Control: no-store`.

### The claim grant

```bash
curl -s https://mcp.corkcli.com/token \
  -d grant_type=urn:workos:agent-auth:grant-type:claim \
  --data-urlencode claim_token=clm_...
```

Until the person has typed the code: `400 authorization_pending`; polled faster than every 5 seconds: `400 slow_down`; the code or the registration expired, or the tokens were already handed over: `400 expired_token`. Then, once: `200` with `access_token` (`cat_...`, 24 hours), `refresh_token` (`crt_...`, 90 days), `token_type`, `expires_in`, `scope` (`collide`), `registration_id`, and a new `identity_assertion` with `assertion_expires` (an hour). The `claim_token` is spent by that poll.

### An identity assertion (jwt-bearer)

```bash
curl -s https://mcp.corkcli.com/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  --data-urlencode assertion=<identity_assertion>
```

Only assertions Cork issued, and recorded when it did, are taken; anything else is `400 invalid_grant`.

- An anonymous registration's pre-claim assertion: `access_token` (`csb_...`), `expires_in` (an hour, never past the registration's end) and `scope` (`sandbox`). Exchange it again as often as needed while it is unclaimed; after the claim it is `invalid_grant`.
- A claimed registration's, or a linked provider identity's: `access_token` (`cat_...`, an hour), `scope` (`collide`), and no refresh token.

### The OAuth code

1. Send the person to `https://mcp.corkcli.com/authorize` with `response_type=code`, your `client_id`, `redirect_uri`, `scope=collide`, `state`, and a PKCE `code_challenge` with `code_challenge_method=S256`. They sign in (Google, GitHub or email) and approve once, choosing the workspaces the client may use.
2. The redirect brings back `code` (valid 10 minutes). Exchange it at `https://mcp.corkcli.com/token` with `grant_type=authorization_code`, the `code`, `redirect_uri`, `client_id` and `code_verifier`.
3. The answer has an `access_token` (`cat_...`, `expires_in` 86400, 24 hours) and a `refresh_token` (`crt_...`, 90 days). Refresh with `grant_type=refresh_token` before the access token expires.

## Use the access_token

Send it as a bearer token, in the `Authorization` header only (`bearer_methods_supported: ["header"]`):

```bash
curl -s https://api.corkcli.com/api/v1/workspaces -H "Authorization: Bearer cat_..."
```

The MCP server takes the same header on every request. The token acts for the person who approved it, in the workspaces they chose, within the repos their seat covers. A viewer seat reads only.

A sandbox token (`csb_...`) is taken by the MCP server alone, for repos named `sandbox/<name>`; every other route treats it as no credential at all.

The machine credential that `cork login` stores in `~/.cork/credentials.json` is a JSON object mapping `<server URL>#<workspace id>` to a token; the hooks and the `cork` command read it. It never goes into a repository.

## Scope

- `collide`: act for the signed-in person in the workspaces they belong to (or the ones they ticked): read briefings and activity, report edits, be collision-checked and message teammates' agents, within the repos their seat covers.
- `sandbox`: an unclaimed anonymous agent's: its own sandbox workspace through the MCP server, repos named `sandbox/<name>`, no agent hours, 1,000 tool calls at 2 a second. Past them, every call answers with the claim endpoint to use.

## Errors

- `401` with `WWW-Authenticate: Bearer resource_metadata="..."`: no token, or it expired. Refresh it, or start again from Discover.
- `403`: the token is valid but its person is not a member of that workspace, or has no seat for that repo.
- `429` with `Retry-After`: too many requests; see the rate limits in the [REST API docs](https://corkcli.com/docs/api.md).
- The identity and claim endpoints answer JSON with `error`, `error_description` and `message`; a `401` also carries `WWW-Authenticate: AgentAuth error="..."`:
  - `400`: `invalid_request`, `invalid_login_hint`, `identity_assertion_not_enabled`, `invalid_issuer`, `invalid_signature`, `invalid_audience`, `expired`, `invalid_client_id`, `replay_detected`, `missing_verified_email`, `email_mismatch`;
  - `401`: `login_required` (with `max_age` 3600), `interaction_required` (with the claim fields), `invalid_claim_token`;
  - `409 claimed_or_in_flight` (already claimed), `410 claim_expired`, `429 rate_limited` or `too_many_attempts`.
- The token endpoint answers OAuth errors as JSON with `error` and `error_description`: `invalid_grant` (an expired or revoked refresh token, a used or expired code, a `client_id` or `redirect_uri` that does not match, a failed PKCE check, an assertion Cork did not issue or that a claim voided), `invalid_request`, `unsupported_grant_type`, and for the claim grant `authorization_pending`, `slow_down` and `expired_token`.
- `/register` answers `400` with `invalid_client_metadata` or `invalid_redirect_uri`, and `429` with `too_many_requests` past the hourly limit. `/authorize` answers `400` with `invalid_request` or `unsupported_response_type`.
- The hooks' own routes answer `200` with `ok: false` and `reason: "unauthorized"` instead, so an agent is never blocked by Cork.

## Revocation

There is no token revocation endpoint (no RFC 7009 `revocation_endpoint`) and no `events_endpoint` for provider events. What ends access:

- a claim revokes everything the registration held before it, at once;
- an unclaimed registration ends at its `claim_token_expires`: its sandbox token stops answering at once and its sandbox is deleted;
- access tokens expire after 24 hours (an hour, from an identity assertion), refresh tokens after 90 days;
- a workspace owner removing a member, or unticking repos for them, takes effect on the next call, whatever tokens they hold;
- deleting the account deletes every access and refresh token it holds.

## The HTTP API

Endpoints, rate limits, idempotency and async jobs: [REST API v1](https://corkcli.com/docs/api.md) and [openapi.json](https://corkcli.com/openapi.json). A few are public: `/api/v1/health`, `/api/v1/plans`, `/artifacts/hooks` and invite previews.
