# Cool Computers credential reference

> Use the minimum credential for direct HTTP API, CLI, browser, or MCP access.

For agent-led registration, follow the generated guide at `https://www.cool.computer/auth.md`. It is the current source of truth for WorkOS agent registration and its claim ceremony.

## Discover

Start here before sending an authentication request:

- Agent registration: `https://www.cool.computer/auth.md`
- This direct credential reference: `https://www.cool.computer/authentication.md`
- HTTP API protected-resource metadata: `https://api.cool.computer/.well-known/oauth-protected-resource`, also linked from protected endpoints' `WWW-Authenticate` challenges.
- MCP protected-resource metadata: `https://api.cool.computer/.well-known/oauth-protected-resource/mcp`
- WorkOS authorization-server metadata: `https://worldly-butterfly-14.authkit.app/.well-known/oauth-authorization-server`
- HTTP contract: `https://www.cool.computer/openapi.json`

MCP clients request `openid`, `email`, and `profile`; they may also request `offline_access` to renew access. WorkOS obtains owner consent for the `/mcp` resource, and the server accepts only tokens issued for that exact resource, an existing Cool Computers owner, and the owner's matching organization. MCP OAuth never creates a Cool Computers account. Read tools require that verified identity. Write tools also check the caller's live `cool-computers:operate` WorkOS permission on every call. The resource exposes per-tool read-only, destructive, and open-world hints.

## Pick a method

- **HTTP or CLI, minimum credential:** existing owners can use the email-code flow below. It returns an access token and refresh token.
- **HTTP, repeated automation:** after email authentication, create an API key. The key is optional and its secret is returned once.
- **Agent registration:** follow `https://www.cool.computer/auth.md` for a claimed, scoped WorkOS agent access token. After the user completes the human claim, the first authenticated request creates their personal Cool Computers account when needed. The short-lived token must contain the `cool-computers:operate` scope.
- **MCP:** connect an OAuth-capable MCP client to `https://api.cool.computer/mcp`. The client follows the MCP protected-resource metadata and opens WorkOS for owner authorization. MCP exposes bounded `cool_*` reads and explicitly requested writes with per-tool read-only, destructive, and open-world hints. A client that cannot do OAuth can send a Cool Computers API key as the bearer instead: tool calls then run on the key's account, as the same key does over HTTP, under the same authentication limits, and a key revoked through the API stops working on MCP at once.
- **Browser:** send an existing owner to `https://www.cool.computer/auth/login?return_to=%2Fapp` to sign in.

The HTTP user access token, agent access token, API key, browser cookie, and MCP OAuth token are separate credential types. Do not substitute one for another; the one exception is that `/mcp` also accepts an API key.

## Authenticate with email

Ask the account owner for the exact email address and approval before starting. The first request immediately sends a real email, so call it once:

```sh
curl https://api.cool.computer/api/auth/email/start \
  -H 'content-type: application/json' \
  --data '{"email":"owner@example.com"}'
```

A successful response has `status: "code_sent"` and an expiry in seconds. Ask the owner for the latest six-digit code, then exchange it:

```sh
curl https://api.cool.computer/api/auth/email/complete \
  -H 'content-type: application/json' \
  --data '{"email":"owner@example.com","code":"123456"}'
```

The completion response returns `access_token`, `refresh_token`, `organization_id`, and `session_id`. Keep credentials out of prompts and logs.

The equivalent CLI flow supports the same two explicit steps:

```sh
cool signup --email owner@example.com --json
printf '%s\n' "$CODE" | cool signup --email owner@example.com --code-stdin --json
```

Run the first command once after approval, then read the latest code from the owner through standard input without adding it to shell history.

## Agent registration

Do not reproduce the agent claim ceremony from this reference. Read `https://www.cool.computer/auth.md` and follow the WorkOS-generated steps exactly. The user must complete the human approval step.

## Use the credential

The access token from email completion is the minimum HTTP credential. Send it as a bearer token and verify the account:

```sh
TOKEN='<access_token>'
curl https://api.cool.computer/api/auth/whoami \
  -H "authorization: Bearer $TOKEN"
```

For repeated HTTP automation, create an API key with the access token. API-key management requires an access token; a browser cookie or existing API key cannot create another key. A claimed agent access token can create a key, but cannot list or revoke keys:

```sh
curl https://api.cool.computer/api/api-keys \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  --data '{"name":"automation"}'
```

Persist the returned API-key secret immediately because it is shown once. Send that secret as `Authorization: Bearer <api_key>` for supported HTTP operations. Read `https://www.cool.computer/openapi.json` before making changes.

For MCP, let the MCP client perform OAuth and store its resource-specific token. MCP credentials do not authorize the mutable HTTP API.

## Errors

HTTP API errors use `application/problem+json` with `code` and `detail` fields, plus `resolution` when there is a concrete next step. A bearer-capable HTTP endpoint returns `401` with a `WWW-Authenticate: Bearer` challenge whose `resource_metadata` points to the API's canonical metadata. A valid bearer without enough authority returns `403` with `error="insufficient_scope"` and names the required `cool-computers:operate` scope. The metadata links the agent registration guide, which defines how to obtain the short-lived scoped credential.

- `400`: fix the request body, email address, or code format.
- `401`: the code or bearer credential is invalid or expired; authenticate again.
- `403`: the credential type or owner authorization is insufficient for that operation.
- `429`: stop and wait before retrying. Do not send another email-code request in a loop.
- `503`: the authentication provider is temporarily unavailable; retry later without changing methods.
- `interactive_required`: give the owner the browser sign-in URL and wait for them to finish.
- `access_token_required`: the route manages API keys, which an API key cannot do; send a user access token from email sign-in instead.
- `invalid_body`: the JSON body is malformed; the `detail` names the unknown field, the wrong type, or the byte where the JSON breaks.
- `unsupported_media_type`: send the JSON body with `Content-Type: application/json`.

## Revocation

Revoke a direct user access token or API key currently in use with:

```sh
curl -X POST https://api.cool.computer/api/auth/logout \
  -H "authorization: Bearer $TOKEN"
```

With a user access token, list API-key IDs at `GET /api/api-keys` and revoke one with `DELETE /api/api-keys/{id}`. Logging out with an API key revokes that key; logging out with a user access token revokes that WorkOS session. Follow `https://www.cool.computer/auth.md` for agent credential and registration revocation. Delete stored credentials after revocation. For MCP, remove the connection through the client that created it and follow that client's displayed revocation behavior; Cool Computers does not publish a separate OAuth revocation endpoint.