Pick a token type
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.
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:...) andreview:reviews:write. - Admin:
resolve:incidents:writeandworkspace:connections:write.
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.
Related
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.