Authentication · Cold OS API

Overview

Every request to the Cold OS API must carry an Authorization: Bearer <key> header. Keys are issued per operator (not per app), inherit that operator’s row-level visibility, and grant the explicit set of scopes selected when the key was created.

Keys never expire automatically. They’re reject-listed the instant you rotate them — there is no propagation lag.

Generating a key

Open Settings → API keys in the Cold OS dashboard.
Click Create key, give it a label that names the integration consuming it.
Pick the smallest set of scopes that integration needs.
Copy the key once — Cold OS never shows the plaintext value again.

Sending the header

Bearer scheme. No URL parameters, no query-string keys. HTTPS is mandatory.

curl https://coldos.justgotwyrd.com/api/v1/users/me \
  -H "Authorization: Bearer $COLD_OS_API_KEY"

Scopes

Scopes are resource:action pairs. Read scopes return data; write scopes mutate; admin:* reaches integration secrets and user records.

contacts:read · contacts:write
pools:read · pools:write
flows:read · flows:write
emails:read · emails:send
tasks:read · tasks:write
calls:read · calls:write
meetings:read · meetings:write
templates:read · templates:write
analytics:read
admin:read · admin:write (workspace-admin role only)

Rotation

Rotating

From Settings → API keys, click Rotate on a row. A new plaintext key is issued; the old one is invalidated immediately. Use the Replace flow if you need a one-call atomic swap (returns the new key + revokes the old in the same transaction).

Suspected leak

Click Revoke. Every in-flight request using that key returns 401 on its next attempt — there is no grace period.

Browser usage

The Try-It panels on these docs are the one exception: keys are stored in the operator’s own browser, never sent to Cold OS, and only used for outbound requests the operator triggered. Persistent (localStorage) mode shows a yellow caution banner.

401 — invalid key

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key not found or revoked.",
    "request_id": "req_01HZSAA1B2C3D4E5F6G7H8J9K0"
  }
}