Skip to main content
Every Public API call carries a token. Pick a personal token for your own scripts, or a service account credential for automation that must outlive any one person.

Pick a token type

For CI/CD, prefer a service account. A pipeline that runs on a personal token breaks the day that person changes role or leaves.

Create a personal token

1

Open API tokens

Open Account Settings → Security → API tokens and click Create token.
2

Name the token and pick a workspace

Enter a Token name that says where it runs, such as laptop-review-script. Pick one Workspace. To reach a second workspace, create a second token.
3

Choose permissions

Under Choose permissions, click Use template on Read CloudThinker, Read reviews or Run reviews, or expand a service and tick Read or Write for each resource. Pick only the scopes the script needs. See Scopes.
4

Set the expiration

Choose 7 days, 30 days (the default), 90 days, 1 year, or a custom date. A token can’t live longer than one year, and every token expires.
5

Review and create

Click Review token, check the permissions and the workspace, then click Create token. Copy the token now. CloudThinker stores only a hash and the last four characters, and can’t show it again.
The page then shows ready-to-paste snippets that set CLOUDTHINKER_TOKEN, CLOUDTHINKER_URL and CLOUDTHINKER_WORKSPACE. Replace <your-token> with the token. CLOUDTHINKER_URL is the app’s origin, https://app.cloudthinker.io, which the CLI uses as its host; curl calls add /api/public to it. In your own scripts, keep the workspace ID in a plain shell variable and pass it to the CLI with -w after the operation name:
The CLI refuses CLOUDTHINKER_WORKSPACE and the global --workspace flag when CLOUDTHINKER_TOKEN is set, and exits with code 2. The page’s CLI snippet unsets it with env -u CLOUDTHINKER_WORKSPACE.

Service accounts

A service account is a workspace member that belongs to no person. Its credentials keep working when people change role or leave.
1

Add the service account

As a workspace Admin, open Workspace settings → Service accounts. Enter an Account name, such as release automation, pick its Workspace role (Viewer, Developer or Admin), and click Create account.
2

Create a credential

Click Manage on the account, then Create credential under API credentials. Choose its permissions and an expiration, the same way as for a personal token. You can only pick scopes the account’s Workspace role allows.
3

Store the credential

Copy the ct_sat_ value into your CI secret store. CloudThinker shows it once.

What a token can do

A call succeeds only when the token has the call’s scope and its owner, a person or a service account, still has that scope’s permission in their current workspace role. So a token never does more than the member behind it.

Scopes

A scope is <area>:<resource>:read or <area>:<resource>:write, for example resolve:incidents:write. A write scope includes the matching read scope. Each endpoint page in the API Reference names the scope it needs. Each scope checks the same permission as the matching button in the app, so the API never refuses what the app lets you do, and never allows what it refuses. The lowest workspace role that has a scope’s permission (a higher role has it too):
  • Viewer: every read scope except Chat.
  • Developer: Chat scopes (chat:...) and review:reviews:write.
  • Admin: resolve:incidents:write and workspace:connections:write.
No token can answer approval requests; answer them in the app. You can only give a token scopes your own role allows; the rest are disabled when you create it. Admins, and organization Owners and Admins, can give any scope. Developers can give every scope except resolve:incidents:write and workspace:connections:write. Viewers can’t create tokens, and see “Viewers cannot create API tokens. Ask a workspace admin for the Developer role.” on the token page. When a call still accepts an older scope, the response carries Deprecation: true and X-CloudThinker-Required-Scope with the scope to use instead. Add that scope to a new token before the old one stops working.

How a call is checked

CloudThinker checks every call in this order and stops at the first failure: Role and membership are checked on every call, so a change takes effect on the owner’s next request: a removed member’s token gets 404 workspace_not_found, and a token with review:reviews:write whose owner becomes a Viewer can only read reviews. GET /v1/token (Read the calling token) lists the scopes a token was given; your current role still applies on each call.

Rotate and revoke

Rotate a token before it expires: create the new token, update the secret where it’s used, confirm a call succeeds, then revoke the old one.

Keep tokens safe

  • Call the API from a server, a script or a pipeline, never from browser or mobile app code, where anyone can read the token.
  • Keep tokens in a secret manager or CI secret, never in source code, tickets, chat or logs. The CLI never logs it.
  • Give each environment and pipeline its own token with only the scopes it needs and the shortest expiry that fits, so revoking one breaks one thing.
  • If a token leaks, revoke it at once, then create a new one, update the secret where it’s used, and work out where the old one was used.

API Errors

Read the error shape and fix a 403 or a 429.

Use CloudThinker in CI/CD

Use a service account credential in a pipeline.