# Cool Computers credential reference

> The credentials of an existing account, and which to use where: email codes, API keys, browser sign-in and MCP OAuth, with their errors and revocation. An agent with no credential follows /agents.md, or /auth.md when it arrived from a 401 challenge.

For agent-led setup, follow the [agent runbook](/agents.md). Agents arriving from a `401` challenge follow [agent registration](/auth.md), which combines Cool Computers' required API audience and continuation steps with the live WorkOS registration guide.

## 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. A `403` with code `sign_up_waitlisted` means the email has no account and no invitation: Cool Computers is invite-only for now, so it joined the waitlist, and WorkOS emails an invitation when it is let in.

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 an owner access token or a claimed agent access token carrying `cool-computers:operate`. For bearer-authenticated requests, listing and revoking keys require an owner access token from email sign-in. An existing API key cannot create, list, or revoke keys through `/api/api-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. Do not retry key creation automatically: the secret cannot be replayed. If the response is lost, ask the owner to inspect their keys before creating another. Send that secret as `Authorization: Bearer <api_key>` for supported HTTP operations. Read `https://www.cool.computer/openapi.json` before making changes.

Signed-in owners can also create, list, and revoke keys in Settings using their browser session. Keep session cookies in the browser; use bearer credentials for scripts.

For MCP, let the MCP client perform OAuth and store its resource-specific token, or configure an API key in a client that supports bearer headers. MCP OAuth tokens do not authorize the HTTP API; API keys work with both interfaces.

## 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 bearer credential is the wrong type for this operation. Use an owner access token from email sign-in. Creating an API key also accepts a claimed agent access token; listing and revoking keys do not. An API key cannot manage keys through `/api/api-keys`; signed-in owners can manage them in Settings.
- `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.