API Keys

Create an API key

POST /v1/api-keys · scope apikeys:write · reversible · idempotent

Returns the plaintext token exactly once. Store it immediately: only its SHA-256 hash is kept and there is no way to recover it later.

curl https://api.truo.cloud/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo auth token create

await truo.apiKeys.create();

operationId: apiKeys.create

Get an API key

GET /v1/api-keys/{id} · scope apikeys:read

curl
SDK

curl https://api.truo.cloud/v1/api-keys/key_42 \
  -H "Authorization: Bearer $TRUO_TOKEN"

await truo.apiKeys.get("key_42");

operationId: apiKeys.get

List the API keys in the account

GET /v1/api-keys · scope apikeys:read

Session only. Never returns tokens: only the prefix and last 4 characters.

curl https://api.truo.cloud/v1/api-keys \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo auth token list

await truo.apiKeys.list();

operationId: apiKeys.list

Revoke an API key

POST /v1/api-keys/{id}/revoke · scope apikeys:write · destructive — cannot be undone · idempotent

Irreversible. Revocation propagates to all replicas over pub/sub in under a second; the worst case, with Redis down, is 60 seconds (the in-process cache TTL).

curl https://api.truo.cloud/v1/api-keys/key_42/revoke \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo auth token revoke key_42

await truo.apiKeys.revoke("key_42");

operationId: apiKeys.revoke

Update an API key

PATCH /v1/api-keys/{id} · scope apikeys:write · reversible · idempotent

Scopes and the allowlist can only be narrowed. Widening returns 403: without that rule, a key with vps:read could promote itself to vps:write with a PATCH and scopes would stop meaning anything.

curl
SDK

curl https://api.truo.cloud/v1/api-keys/key_42 \
  -X PATCH \
  -H "Authorization: Bearer $TRUO_TOKEN"

await truo.apiKeys.update("key_42");

operationId: apiKeys.update