API Tokens

An API token, also called an API key, lets a script, a CI job, the CLI, an SDK, Terraform or an AI agent act as you on Cloady. Every request it makes runs with your account, in the workspaces you belong to and with your role in each, limited by the token's scope.

A token looks like this: cldy_ followed by 48 hexadecimal characters.

cldy_3f9a1c07d2b84e65a0c9e1f4b7d2a8c6e05f19b3a7d4c2e8

Create a token in the dashboard

1. Click your account avatar in the top-right corner, then Account settings.
2. Open the API tokens tab and click + New token.
3. Give the token a name that says where it will be used, such as GitHub Actions or CLI · laptop. You'll see the name in the list later.
4. Choose a scope: Read only, Deploy only or Full access. See Scopes for what each one allows.
5. Choose an expiry: No expiry, 30 days, 90 days or 1 year.
6. Click Create token.
7. Copy the token right away. Cloady shows it once and stores only a hash of it, so it can't be shown again. If you lose it, revoke it and create a new one.

Keep the token somewhere safe, such as your CI provider's secret store or a password manager. Never paste it into a support ticket, a chat or a public repository.

Scopes

Every token has one scope. The scope sets the highest workspace role the token can act with; your own role in each workspace still applies on top.

Pick the narrowest scope that does the job:

• A CI pipeline or an AI coding agent that deploys: Deploy only.
• A dashboard, monitor or report that only reads: Read only.
• Terraform that creates workspaces, or anything that changes billing: Full access.

A request that needs more than the token's scope gets 403 forbidden, even if your own role in the workspace is higher.

Use the token

HTTP API

Send the token as a bearer token on every request to https://cloady.com/api:

curl https://cloady.com/api/workspaces \
  -H "Authorization: Bearer cldy_…"

CLI

cloady login cldy_…

The CLI stores the token in ~/.config/cloady/config.json. It also reads CLOADY_TOKEN from the environment, which suits CI jobs, and takes --token cldy_… on any command. See the CLI guide.

SDKs

import { createCloady } from "@cloady/sdk";

const cloady = createCloady({ auth: process.env.CLOADY_TOKEN });

from cloady import Cloady

cloady = Cloady(base_url="https://cloady.com", token="cldy_…")

Terraform

The provider reads CLOADY_TOKEN, or a token argument on the provider block. See the Terraform guide.

export CLOADY_TOKEN=cldy_…

MCP

The @cloady/mcp server reads the token from BEARER_TOKEN_CLOADY:

claude mcp add cloady -e BEARER_TOKEN_CLOADY=cldy_… -- npx -y @cloady/mcp

Clients that connect to the hosted server at https://cloady.com/api/mcp sign in through your browser instead, and Cloady creates the token for them. See the MCP guide.

Tokens Cloady creates for you

Some sign-ins create a token on your behalf, and these show up in the same list:

• cloady login without a token signs in through your browser and creates a token named Cloady CLI.
• Connecting an MCP client or an AI app such as Claude or ChatGPT to Cloady creates a token named after that client, with the scope you pick on the consent page.

Revoking one of these tokens signs that tool out.

Create a token over the API

A token with Full access, or a signed-in browser session, can create another token:

curl https://cloady.com/api/me/tokens \
  -H "Authorization: Bearer cldy_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "GitHub Actions", "scope": "deploy", "expires": "90d"}'

The response carries the new token's details and, once only, its value in secret:

{
  "token": {
    "id": "…",
    "name": "GitHub Actions",
    "scope": "deploy",
    "prefix": "cldy_3f9a1c0",
    "workspaceId": null,
    "lastUsedAt": null,
    "expiresAt": "2027-02-01T12:00:00.000Z",
    "createdAt": "2026-11-03T12:00:00.000Z"
  },
  "secret": "cldy_…"
}

See createToken, listTokens and revokeToken for the full reference.

See and revoke tokens

Account settings → API tokens lists every active token with its name, scope, the first 12 characters of its value (cldy_3f9a1c0), when it was last used and when it expires. Click Revoke to turn a token off; it stops working at once.

Over the API, GET /api/me/tokens lists your tokens and DELETE /api/me/tokens/{id} revokes one.

Revoke a token when the person, machine or service using it no longer needs it, and right away if it might have leaked. Then create a new one.

Errors

For how scopes and workspace roles combine on every request, see the API overview.