client_id and client_secret for a short-lived JWT bearer token.
Flow
Request
POST /_api/auth
| Field | Type | Required | Description |
|---|---|---|---|
client_id | string | Yes | API credential identifier |
client_secret | string | Yes | API credential secret |
scopes | string[] | Yes | Fine-grained permissions to request (see Scopes) |
api_version | string | No | API contract date (YYYY-MM-DD). Defaults to credential default or 2026-07-02 (beta) |
Response
| Field | Type | Description |
|---|---|---|
access_token | string | JWT bearer token |
token_type | string | Always "Bearer" |
expires_at | string | ISO 8601 expiry timestamp |
JWT claims
The access token is an HS256 JWT with these claims:| Claim | Description |
|---|---|
client_id | API credential ID |
tenant_id | Tenant the credential belongs to |
scopes | Granted fine-grained permissions |
api_version | Locked API contract version (e.g. 2026-07-02, currently beta) |
iss | st-external-api |
aud | st-api |
iat / exp | Issued at / expiry (10-minute TTL) |
Token validity
Access tokens are valid for 600 seconds (10 minutes). After expiry, callPOST /_api/auth again.
Response headers
| Header | Description |
|---|---|
ST-Api-Version | API contract version used for the response (e.g. 2026-07-02) |
ST-Api-Version-Beta | true for beta versions — sent on all 2026-07-02 responses |
Using the token
Include the token on all protected requests:Using the API playground
The API Reference includes an interactive playground on each endpoint. You do not need to paste your bearer token on every request — set it once and reuse it across endpoints.Get an access token
Open Authenticate (
POST /_api/auth) in the API Reference. Run the request with your client_id, client_secret, and scopes. Copy the access_token from the response.Authorize once
In the API Reference, open the Auth (or Authorize) section. Paste your
access_token into the bearer token field. You do not need to include the Bearer prefix — the playground adds it automatically.Try any endpoint
Navigate to any protected endpoint and use Try it. The playground sends your saved token on every request until you clear it or it expires.
The playground stores your token in your browser’s local storage for this documentation site. It persists when you move between endpoints and refresh the page, but it is not shared across browsers or devices.
Failed authentication alerts
After 3 consecutive failed authentication attempts for the same API credential, an email notification is sent to the tenant administrators. The API credential is not automatically disabled. If you receive repeated failure alerts, verify yourclient_id and client_secret, confirm you are calling the correct environment base URL, and rotate the credential if the secret may have been compromised.
Security notes
- Never expose
client_secretin client-side code or public repositories - Store credentials in environment variables or a secrets manager
- Request only the scopes your integration needs