Developers
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 /setup.md, or /auth.md when it arrived from a 401 challenge.
For agent-led setup, follow setup.md. Agents arriving from a 401 challenge follow agent registration, 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-Authenticatechallenges. - 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.mdfor 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 thecool-computers:operatescope. - 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 boundedcool_*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=%2Fappto sign in. When the CLI is signed in with an email code,cool browser <address>(POST /api/auth/browser-handoff) instead opens that page already signed in, with no second code; the browser stays signed in untilcool logout, a revoke or the sign-in expiring ends the CLI's WorkOS session, and is signed out within two minutes of that.
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:
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:
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 Cool Computers is full right now and the email has no account and no invitation, 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:
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:
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:
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; thedetailnames the unknown field, the wrong type, or the byte where the JSON breaks.unsupported_media_type: send the JSON body withContent-Type: application/json.
Revocation
Revoke a direct user access token or API key currently in use with:
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.