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_…orsk_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.
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.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.