# Cool Computers authentication

> Access an existing account with WorkOS, then obtain the minimum credential for the HTTP API or MCP. New account creation is temporarily paused.

New owners should [join the waitlist](/#waitlist). The authentication methods below remain available to existing owners.

## Discover

Start here before sending an authentication request:

- This guide: `https://www.cool.computer/auth.md`
- HTTP API protected-resource metadata: `https://api.cool.computer/.well-known/oauth-protected-resource` for the API origin, or the path-specific URL from a protected endpoint's `WWW-Authenticate` challenge.
- 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. The HTTP API does not advertise operation-level OAuth scopes or an authorization server because it uses the email-code flow and Cool Computers API keys documented below. WorkOS Agent Registration is not enabled for this service, so its authorization-server metadata has no `agent_auth` block. No Cool Computers agent-registration or claim endpoint exists.

## 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.
- **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.
- **Browser:** send an existing owner to `https://www.cool.computer/auth/login?return_to=%2Fapp` to sign in.

The HTTP access token, API key, browser cookie, and MCP OAuth token are separate credential types. Do not substitute one for another.

## 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.

## Claim

There is no separate agent claim-token ceremony. Successful email-code completion verifies control of the email address and reuses that owner's existing account. If WorkOS requires additional interactive verification, stop the email flow and give the owner the browser sign-in URL. Do not access an account without the owner's inbox access or interactive approval.

## 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:

```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`, `detail`, and `resolution` fields. A bearer-capable HTTP endpoint returns `401` with a `WWW-Authenticate: Bearer` challenge whose `resource_metadata` points to metadata for that exact requested resource. That metadata names bearer-header support and links back to this guide; it does not claim the MCP authorization server can issue HTTP API credentials.

- `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.

## Revocation

Revoke the bearer credential currently in use with:

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

With an 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 an access token revokes that WorkOS session. Delete stored access, refresh, API-key, or MCP tokens 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 MCP revocation endpoint.