API tokens & service accounts¶

For anything you'd do in the Console, there's an API. To call it, you need an API token (for a user) or a service account (for a non-human caller).

What's the difference?¶

Rule of thumb: anything that runs without a human at the keyboard should use a service account, not a user's personal token. Otherwise the moment that user changes role or leaves, your pipeline breaks (and you may scramble to issue a new token with the same scope).

Issuing a personal API token¶

User menu → Account → API tokens → + New token.

Creating an API token. Scope and lifetime are mandatory; the secret is shown exactly once.

The form asks:

Click Create. Cloud Digit shows the token value exactly once — copy it now. After this screen, only the prefix is shown (e.g. cd_a1b2c3...), never the full secret.

Storing the token¶

• CI/CD systems — store in the platform's encrypted secret store (GitHub Actions secrets, GitLab CI variables, etc.). Never commit to git.
• Local development — use the OS keychain (macOS Keychain, Windows Credential Manager) via the Cloud Digit CLI's cd configure command, which stores it for you.
• Plain files — last resort. If you must, put the file in ~/.config/cd/token with chmod 600.

Rotating¶

Tokens can't be rotated in place — you generate a new one, deploy it, then revoke the old one. The Console makes this convenient: from the token list, click ⋯ → Rotate. Cloud Digit creates a new token with the same scope and a 7-day grace window during which both work, so you have time to deploy the new value before the old one stops.

Service accounts¶

Project settings → Service accounts → + New service account.

Service accounts page inside a project. Each row is a non-human identity.

The form:

After creating the service account, you issue a token for it (same flow as a personal token, scoped to the service-account identity). A service account can have multiple active tokens — useful when you're rotating, or running parallel deployers across regions.

Service-account access keys (S3)¶

For Object Storage, service accounts can also have S3-style access key / secret key pairs in addition to OIDC API tokens. Issue from Service accounts → choose account → Access keys → + New key. These are S3-compatible — drop them into any AWS SDK with the right endpoint URL.

Using a token¶

CLI¶

```bash cd configure # interactive — prompts for token

or¶

export CD_API_TOKEN="cd_xxxxxxxx..." # for one-off invocations cd compute server list ```

Terraform¶

hcl provider "clouddigit" { region = "bd-dha-1" # token via env var CD_API_TOKEN }

Raw HTTP¶

bash curl -H "Authorization: Bearer cd_xxxxxxxx..." \ https://api.bd-dha-1.clouddigit.ai/v1/compute/servers

OpenStack / S3¶

The same OIDC-issued token also works as a Keystone token (OpenStack APIs) and the S3 path uses access keys instead of bearer tokens.

Token best practices¶

Revoking¶

From the token list (Account → API tokens for personal, or Service accounts → tokens for service):

1. Click ⋯ on the token row
2. Revoke
3. Confirm

Revocation is immediate — the next API call with that token gets 401 Unauthorized within ~5 seconds (token caches at the edge are sub-second).

For emergency revocation of all of a user's tokens at once: org Admin / Owner → Members → ⋯ → Revoke all tokens. Useful when a laptop is lost.

Audit trail¶

The audit log records, for every API call:

• Token name + prefix (never the full secret)
• Caller identity (user email or service-account name)
• API method + path + parameters
• Result (status code, error code)
• Source IP
• Timestamp

Export from the audit log or push to your SIEM.

Related¶

• Reference → API & CLI
• Roles & permissions
• Users
• Object Storage (S3)
• Compliance & sovereignty