Skip to main content
The API uses the OAuth 2 client credentials grant. Your server holds an OAuth client’s ID and secret, exchanges them for a short-lived access token, and sends that token on every request.

OAuth clients

Create clients in the dashboard under Settings → OAuth clients. Each client has:
  • An environment, test or live, fixed when it’s made. Its tokens can only act in that environment. See Environments.
  • Scopes: what its tokens may do. You can change them later; removing a scope stops existing tokens using it on their next request.
  • A secret (sk_test_… or sk_live_…), shown once when the client is created or its secret is rotated. Keep it on your server. Never put it in a browser, a mobile app or source control.
You can rotate a client’s secret (the old one stops working immediately) or revoke the client, which ends every token it issued.

Getting a token

POST https://idp.talescria.com/oauth/token with grant_type=client_credentials. Authenticate with HTTP Basic (client_id:client_secret), or send client_id and client_secret in the form body, but not both.
scope is optional. Leave it out to get every scope the client holds, or list fewer to get a token that can do less than its client. Asking for a scope the client doesn’t hold is invalid_scope.

Refreshing

When an access token expires, either request a new one with client credentials or use the refresh token. Refreshing also needs the client’s credentials.
Each refresh returns a new refresh token. Use the new one next time: presenting a refresh token that has already been used is treated as theft, and every token descended from it is revoked.
The simplest approach for a server is to cache the access token and fetch a new one with client credentials shortly before expires_in runs out.

Scopes

write includes read for the same resource. Give each client only what it needs. A reporting job needs read scopes; only the service that pays people needs payments:write.

When a request is refused

A 401 means “we don’t know who you are” and a 403 means “we do, and this isn’t allowed”. Handle them separately: retrying a 403 with a fresh token won’t help.