Authentication

Every API call carries a token. Here's how to get one and how long it lasts.

There are two ways to authenticate, and one of them is right for almost everyone:

• Personal access token (recommended). Generate it once in the dashboard under API Keys, and send it on every request as Authorization: Bearer YOUR_TOKEN. No client IDs, no sign-in flow, no expiry to manage. It keeps working even if your dashboard login is ever locked after failed sign-in attempts. This is the right choice for connecting your own system to the API.
• App credentials (OAuth 2.0). For apps that act on behalf of your own customers: your users sign in to Shout About Us from inside your product and your app receives a token that acts as them. Creates a client ID and secret. Most partners don't need this. See App credentials (OAuth 2.0).

If your integration authenticates with an email and password, it keeps working. New integrations should use a personal access token.

Locks and tokens. A dashboard login locks temporarily after repeated failed sign-ins: locks start at one minute, grow to a fifteen-minute maximum, then lift automatically. A lock does not disable an existing personal access token; tokens keep working until you regenerate or revoke them.

Choose your method

What your token can reach. A partner token acts on everything under your partner. An account token is limited to that account and its locations. Every endpoint page says which it accepts.

Using the token

Send it on every protected call:

Authorization: Bearer <bearer-token>

Token lifecycle

Tokens are OAuth 2.0 bearer tokens issued by our authorization server (RS256-signed JWTs).

• Personal access tokens do not expire — rotate them from the API Keys page (regenerating revokes the previous token immediately).
• App credentials (OAuth 2.0) access tokens last 1 day. Their refresh tokens last 30 days (see App credentials (OAuth 2.0) for the refresh call).
• Check any token with GET /verify-token — it returns the user and company while the token is valid, and 401 once it expires or is revoked.
• Revoke a token at any time (for example on sign-out) with GET /sso/revoking-token, sending the token as the Bearer header.

Locked accounts

Five wrong password attempts temporarily lock an account (starting at 1 minute and growing to a 15-minute maximum, lifting automatically). While locked, new sign-ins are refused; tokens issued earlier keep working until they expire or are revoked.

Public vs protected

Public (no token): POST /auth/discover, email OTP verification, the SSO redirect / callback / exchange legs, and the OAuth endpoints at the server root (/oauth/authorize, /oauth/token). Everything else requires a bearer token.

Before you begin

Create your app credentials (client_id + client_secret) on the dashboard's API Keys page — they are needed for App credentials (OAuth 2.0). The client secret is shown once, at creation. Personal access tokens need no app credentials.

Prerequisites

• A bearer token in the Authorization header. Any endpoint that needs no token says so on its own page.
• The id of each record the call targets. Every endpoint page lists the ids it needs.

Errors

Individual endpoints may return more; each page lists its own.

Sections

Endpoints