---
title: "Cool Computers API authentication"
description: "Sign up or sign in to Cool Computers, create an API key, and keep HTTP and MCP credentials separate."
canonical: "https://www.cool.computer/docs/api-reference/authentication"
last_updated: "2026-11-20"
---
# Cool Computers API authentication

> Sign up or sign in to Cool Computers, create an API key, and keep HTTP and MCP credentials separate.

The HTTP API uses the same email-code flow for new and existing Cool Computers accounts. Completing verification creates your account if needed.

For the complete agent-led setup, follow the [agent runbook](/agents.md). For standards-based WorkOS agent registration, follow [the registration guide](/auth.md) and have the owner complete its human approval step.

## Choose a credential

| Credential                            | HTTP API                                     | MCP                                                                                        | API-key management                                           |
| ------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| Owner access token from email sign-in | Owner-authorized requests.                   | Use MCP OAuth or an API key.                                                               | Create, list, and revoke keys.                               |
| Claimed WorkOS agent access token     | Requires the `cool-computers:operate` scope. | Use MCP OAuth or an API key.                                                               | Create a key only.                                           |
| Cool Computers API key                | Repeated automation on the key's account.    | Accepted as a bearer credential.                                                           | Cannot create, list, or revoke keys through `/api/api-keys`. |
| MCP OAuth token                       | Does not authorize the HTTP API.             | Authorizes the MCP resource. Signing in through an MCP client can also create the account. | Cannot manage keys.                                          |

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.

A claimed agent's first authenticated HTTP request creates the owner's personal Cool Computers account when needed. Follow the registration guide for the required audience, claim ceremony, and token renewal.

## 1. Send a code

Ask the owner for the exact email address and approval before starting. The next request emails a sign-in code to that address:

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

Do not repeat the request while waiting. Ask the owner for the latest six-digit code.

## 2. Complete sign-in

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

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

## 3. Create an API key

Use the access token to create a key for repeated automation:

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

The API returns the secret once. Do not automatically retry key creation after a timeout; the first request may already have created a key whose secret you did not receive. A claimed WorkOS agent access token can also create a key through this endpoint. For bearer-authenticated requests, listing and revoking keys require an owner access token from email sign-in. An API key cannot create, list, or revoke keys through `/api/api-keys`.

## Revoke access

For an owner access token or API key, revoke the bearer credential used for the request:

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

Logging out with an API key revokes that key. Logging out with an owner access token revokes its session. Use `GET /api/api-keys` and `DELETE /api/api-keys/{id}` with an owner access token to list and revoke API keys. Follow the [registration guide](/auth.md) for agent credential and registration revocation.

## MCP authentication

An MCP client follows protected-resource metadata at `https://api.cool.computer/.well-known/oauth-protected-resource/mcp` and completes its own OAuth flow. Signing in that way can also sign a new user up. The token authorizes only the MCP resource. Write tools also check the owner's live `cool-computers:operate` permission. The token does not authorize the HTTP API.

Clients that cannot complete OAuth can send a Cool Computers API key as `Authorization: Bearer <api_key>` to the MCP endpoint. Tool calls run on that key's account. Revoking the key also removes its MCP access.

Read the [credential reference](/authentication.md) for discovery, errors, and interactive sign-in requirements.
