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

  1. Make a code verifier (43 to 128 random characters) and its S256 challenge, the base64url SHA-256 of it.

  2. Open /oauth/authorize in the system browser, never a web view, with client_id, redirect_uri (exactly as registered), response_type=code, code_challenge, code_challenge_method=S256 and a state of your own. The person signs in as they do on the website.

  3. The browser comes back to your redirect with code, your state (check it) and iss. The code lasts 60 seconds and works once.

  4. POST /v1/auth/token, form-encoded: grant_type=authorization_code, code, code_verifier, redirect_uri, client_id, and the device's name as device_name. You get an access token for 15 minutes and a refresh token.

  5. When the access token expires, POST /v1/auth/token with grant_type=refresh_token, refresh_token and client_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.

On this page