Authentication
The SSN API uses OAuth2 client credentials for server-to-server integrations.
SSN supplies a separate client_id and client_secret for each environment.
Keep the secret on your server, never in browser code or source control.
Request and use a token
Send credentials in the form body (HTTP Basic authentication is not supported):
POST /api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET
Form-encode values. JSON bodies are also accepted. Optional scope is a
space-separated subset of the scopes granted to the credential. If omitted,
the token receives all granted scopes. Requesting an ungranted scope returns
400; invalid credentials return 401. If an outbound IP allowlist was assigned,
token requests must originate from an allowed address.
Send the returned token as Authorization: Bearer YOUR_ACCESS_TOKEN on protected
requests. Read expires_in from the token response (the default is one hour),
cache the token until near expiry, and request a new one when needed. There is no
refresh-token flow. A secret rotation prevents new token requests with the old
secret; already-issued tokens remain usable until expiry.
Required scopes
Read and write scopes are independent: write permission does not include read. Scopes authorize operations within the credential's tenant; they do not grant access to another tenant's records.
| Scope | Allowed operations |
|---|---|
sites:read | List and read sites |
sites:write | Create and update sites |
site-visits:read | List/read visits, project and item references, assigned assets, and return labels |
site-visits:write | Create/update visits, assign siteAssetIds, and upload return labels |
messages:read | List/read messages and download attachments |
messages:write | Create/update messages and upload attachments |
webhooks:read | List webhook subscriptions |
webhooks:write | Create/update webhook subscriptions, including disabling them |
There are no separate site-asset scopes. Missing required token scopes return
403. Ask SSN to grant approved additional access, then request a new token;
existing tokens do not gain newly granted scopes. Administrator portal sign-in
uses a separate access system and does not use client API credentials.
Follow the quickstart for a complete request sequence, environment guide for endpoint selection, and error and retry guide before repeating a failed request.