Authentication
How an app, a server or a script gets a token, and what it may do.
Every call except signing in carries a token: Authorization: Bearer s2a_…. Tokens are opaque: don't read anything into them except their beginning, which says the region they belong to. A missing, expired or revoked token is 401 with WWW-Authenticate: Bearer error="invalid_token".
For an app acting for a person: OAuth 2.1 with PKCE
Make a code verifier (43 to 128 random characters) and its
S256challenge, the base64url SHA-256 of it.Open
/oauth/authorizein the system browser, never a web view, withclient_id,redirect_uri(exactly as registered),response_type=code,code_challenge,code_challenge_method=S256and astateof your own. The person signs in as they do on the website.The browser comes back to your redirect with
code, yourstate(check it) andiss. The code lasts 60 seconds and works once.POST /v1/auth/token, form-encoded:grant_type=authorization_code,code,code_verifier,redirect_uri,client_id, and the device's name asdevice_name. You get an access token for 15 minutes and a refresh token.When the access token expires,
POST /v1/auth/tokenwithgrant_type=refresh_token,refresh_tokenandclient_id. Each refresh token works once: keep the new one. Presenting a used refresh token signs the device out, in case it was stolen.
Signing apps in is for our own apps during version 0; registering your own app, with a consent screen, arrives with version 1.
For a server: client credentials
An administrator makes a client in Settings › API: it acts in one workspace as a member they choose. POST /v1/auth/token with grant_type=client_credentials, authenticating with HTTP Basic (the client ID and secret), gives a 15-minute access token. There is no refresh token: ask again. Each client has two secrets at most, so you can change one without a gap.
For your own scripts: personal tokens
Make one in Settings › Devices and tokens. It acts as you, starts s2a_pat_, is shown once and lasts up to a year.
Signing out
POST /v1/auth/revoke, form-encoded, with token (and client_id for an app). It always answers 200. Revoking an app's token signs that device out; a person can also sign devices out from the website.
What a token may do
Scopes name a module, a resource and a verb, such as documents:envelopes:write or timeoff:requests:read. A token can only ever do what its scopes allow and what the person it acts for can do in the app today; when someone loses a permission, every token acting for them loses it at once. Every call is recorded in the audit trail with the client and the person.
Limits on the token endpoint
30 requests a minute from one address and 60 a minute for one client. Over that, 429 with Retry-After.