Skip to main content

Create and manage Cloider API tokens

View as MarkdownOpen in ClaudeOpen in ChatGPT

An API token lets a script, a CI pipeline, the cloider CLI, the Terraform provider, the MCP server or your own code call the Cloider API without a browser. A token looks like cldr_ followed by 40 random characters, works in one account, and acts as the member who generated it, with Read or Read & Write access.

At a glance​

Formatcldr_ + 40 characters, for example cldr_xxxxxxxxxxxxxxxxxxxxxxxx
ScopeOne account, as the member who generated it, never more than that member's current role
Access levelsRead (only read requests) or Read & Write
ShownOnce, when generated. It can't be displayed again
ExpiryNone. A token works until it is deleted, or its creator is removed or deactivated
Limit50 tokens per account; description up to 100 characters
Managed inThe dashboard only: Access Control, API Tokens
Used asAuthorization: Bearer cldr_..., CLOIDER_TOKEN, CLOIDER_TOKEN_FILE, or cloider login

Read or Read & Write?​

AccessCanCan'tUse it for
ReadEvery read (GET) request: list and show resources, usage, logs, kubeconfigs, database passwordsCreate, change or delete anything, open terminals, run exec. Writes fail with This API token is read only!Monitoring, dashboards, terraform plan, AI agents that only look
Read & WriteEverything its creator's role allowsManage members and tokens, connect Git providers (dashboard only)Deploys, CI, terraform apply, the CLI on your computer

A token never has more access than its creator: a Read & Write token generated by an Admin acts as an Admin, and its access drops at once if the Admin is made Restricted. Restricted members can only generate Read tokens. The Billing endpoint only answers a Read & Write token generated by the Owner. See the permission matrix.

Generate a token​

  1. Open Access Control in the sidebar and choose the API Tokens tab.
  2. Click Generate API token.
  3. Type a Description that says where the token will be used, for example GitHub Actions deploy or terraform. You'll see it in the token list later.
  4. Under Permissions, choose Read (the default) or Read & Write.
  5. Click Generate API token.
  6. The API token generated dialog shows the token and a Try it curl command. Copy the token now: This is the only time it is shown, and it can't be recovered.
  7. Click I've saved the token.
The API token generated dialog warning to copy the token now, showing the token, a Try it curl command and the I've saved the token button
The token is shown once. Copy it before you close the dialog.
The Generate API token dialog with a Description field and Permissions set to Read or Read & Write
Generating an API token. Read is selected by default.

Use a token​

Send the token as a bearer token in the Authorization header of every API request:

curl -H "Authorization: Bearer $CLOIDER_TOKEN" https://cloider.com/api/clusters

The CLI and the Terraform provider read it from the environment:

export CLOIDER_TOKEN=cldr_xxxxxxxxxxxxxxxxxxxxxxxx
cloider cluster list

For a token kept in a file, such as a mounted secret, use CLOIDER_TOKEN_FILE=/run/secrets/cloider-token or the CLI's --token-file flag.

In GitHub Actions​

Store the token as a repository secret named CLOIDER_TOKEN, then expose it to the steps that need it:

.github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      CLOIDER_TOKEN: ${{ secrets.CLOIDER_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://cloider.com/install.sh | sh
      # the script installs to ~/.local/bin when /usr/local/bin is not writable
      - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: cloider deploy --app blog

More in CI/CD with GitHub Actions and CI/CD with GitLab.

Check what a token can do​

GET /api/whoami tells you who a token acts as, in which account, with which role, and whether it is read only:

curl -H "Authorization: Bearer $CLOIDER_TOKEN" https://cloider.com/api/whoami
Response
{
  "user": {"first_name": "Jane", "last_name": "Doe", "email": "jane@acme.com", "picture": "https://...", "plan": "Paid", "trial_end_date": null, "suspended": false},
  "account": {"first_name": "Acme", "last_name": "Inc", "email": "ops@acme.com", "picture": "https://...", "plan": "Paid", "trial_end_date": null, "suspended": false},
  "role": "Admin",
  "token": {"hashed_id": "t4k9p", "description": "GitHub Actions deploy", "read_only": false, "creator": {"first_name": "Jane", "last_name": "Doe", "email": "jane@acme.com", "picture": "https://..."}, "last_used_at": "2026-10-20T08:01:00Z", "created_at": "2026-09-02T10:20:00Z"}
}

cloider whoami prints the same as a table.

List tokens​

The API Tokens tab listing tokens with their Description, Permission, Created by, Last used and Created at columns
The API Tokens tab. Owners and Admins see every token in the account.

The API Tokens tab lists each token's Description, Permission (Read or Read & Write), Created by (for Owners and Admins), Last used and Created at. Owners and Admins see every token in the account; other members see only their own.

cloider token list
Output
DESCRIPTION                     ACCESS        CREATED BY      LAST USED  CREATED           THIS CLI
Cloider CLI on janes-macbook    Read & Write  jane@acme.com   just now   2026-09-02 10:20  *
GitHub Actions deploy           Read & Write  jane@acme.com   3h ago     2026-09-04 09:12
grafana                         Read          sam@acme.com    never      2026-10-01 14:30

The * marks the token the CLI is using. Last used is updated at most once a minute.

Edit a token​

You can change a token's description and its permission without generating a new one:

  1. In API Tokens, click the pencil icon (Edit) on the token's row.
  2. Change the Description or the Permissions.
  3. Click Save changes.

Owners and Admins can edit any token in the account. A token can't be given Read & Write if its creator is Restricted.

Delete (revoke) a token​

Deleting a token revokes it: anything still using it loses access right away.

  1. In API Tokens, click the delete icon on the token's row.
  2. Confirm. The dialog warns that Anything still using it loses access right away.

Tokens are also deleted automatically when their creator is removed from the account, and stop working while their creator is deactivated.

If a token leaks​

  1. Delete it in Access Control, API Tokens straight away. It stops working on the next request.
  2. Generate a new token with a new description and update the places that used the old one.
  3. Check Usage and your resources for changes you didn't make.

The cldr_ prefix makes leaked tokens easy to find with secret scanning tools.

Troubleshooting​

MessageHTTP statusCause and fix
Invalid or revoked API token!401The token was deleted, mistyped, or its creator was removed or deactivated. Check CLOIDER_TOKEN and generate a new token if needed.
This API token is read only!403A Read token tried to change something. Use a Read & Write token.
Terminals need a Read & Write API token!403Terminals can't be opened with a Read token.
This endpoint can't be used with an API token!403Members, tokens, account switching and Git connections are dashboard only.
An account can have up to 50 API tokens, delete one you no longer use!400Delete unused tokens first.
Description is required! or Description can be up to 100 characters400Give the token a short description.
Read & Write needs write access to this account, Restricted members can only have Read tokens400Your role is Restricted. Choose Read.

More in Troubleshooting and API authentication.

Next steps​

Frequently asked questions

How do I create a Cloider API token?

Open Access Control in the dashboard, choose the API Tokens tab, click Generate API token, type a description, choose Read or Read & Write and click Generate API token. Copy the token from the dialog: it is shown only once.

Do Cloider API tokens expire?

No. A token works until it is deleted, or until its creator is removed from the account or deactivated.

I lost my API token. Can I see it again?

No. A token is shown only once, when it is generated, and can't be displayed again. Delete the lost token and generate a new one.

Can an API token create another API token?

No. Tokens are generated, edited and deleted in the dashboard only. The only change a token can make is to revoke itself with DELETE /api/api-tokens/current.

How many API tokens can an account have?

Up to 50. Delete tokens you no longer use to make room.

Which token does Terraform need?

terraform plan works with a Read token. terraform apply needs a Read & Write token.

Can a token work in several accounts?

No. A token belongs to the account it was generated in. Use one token per account, for example with CLI profiles or one Terraform provider block per account.

Last updated on