POST /v1/service-account-tokens with a name and the scopes you need
A service-account token is a bearer credential for your server code: pick a name, grant only the scopes the integration needs, and the plaintext value comes back exactly once.
Creating one#
POST /v1/service-account-tokens runs under your normal login (session or API key) and accepts { "name", "scopes", "expiresInDays" }. The name is mandatory (A token name is required.), expiresInDays is optional, and omitting scopes grants read. The response is 201 { "token": … } where the value is sat_ followed by 32 random bytes, base64url-encoded — copy it now, because only its SHA-256 hash is stored.
Scopes#
Valid scopes are read, write, and webhooks — trimmed, lower-cased, and de-duplicated on the way in. Anything else answers Unknown scope "x". Valid scopes: read, write, webhooks., and an empty list answers At least one scope is required. Every public-API route declares the scope it requires; a token missing it is rejected as out-of-scope at authentication time.
Limits and lifetime#
Each tenant may hold at most 20 active tokens (A tenant can have at most 20 active service-account tokens.). Without expiresInDays the token never expires, but it dies the moment it is revoked or the tenant is disabled. GET /v1/service-account-tokens lists everything newest-first as previews (sat_ab12cd34…wxyz) — the full value never appears again after creation.