Exchange a user's email and password for an access token and a refresh token, using the OAuth 2.0 Resource Owner Password Credentials grant served by our OAuth 2.0 authorization server.
Exchange a user's email and password for an access token and a refresh token, using the OAuth 2.0 Resource Owner Password Credentials grant served by our OAuth 2.0 authorization server.
Use this for trusted first-party server integrations that need long-lived access. POST /api/v1/login also returns a token, but without a refresh token — this grant is the refreshable alternative.
Where this endpoint lives. The token endpoint sits at the server root, not under/api/v1:
https://production-api.shoutaboutus.com/oauth/token.
Every other endpoint in this API is versioned under/api/v1. This one is not.
Prerequisites
Before your first call you need an OAuth client:
| You need | How to get it |
|---|---|
client_id | Ask an administrator. It is a public identifier and safe to store in config. |
client_secret | Ask an administrator. It is shown once, when the client is created, and cannot be retrieved afterwards. |
| A user's email + password | The end user whose access you are requesting. |
Store the secret server-side only — see Security below.
1 — Get a token
Send POST /oauth/token as application/x-www-form-urlencoded with these fields:
| Field | Required | Notes |
|---|---|---|
grant_type | Required | password |
client_id | Required | Your OAuth client id |
client_secret | Required | Your OAuth client secret |
username | Required | The user's email address |
password | Required | The user's password |
scope | Optional | * requests full access |
A success returns token_type, expires_in, access_token and refresh_token. Send the access token as an Authorization: Bearer <bearer-token> header on every other call.
2 — Check a token is still valid
Call GET /api/v1/verify-token with the access token. It returns the user and company while the token is valid, and 401 Unauthenticated once it expires or is revoked. Use it to decide whether to refresh before making a real request.
3 — Refresh the token
Access tokens last 1 day; refresh tokens last 30 days. When the access token expires, POST /oauth/token again with grant_type=refresh_token, your stored refresh_token, client_id, client_secret and scope.
You get back an account-new access token and an account-new refresh token. The old refresh token is consumed immediately, so always persist the new one — otherwise the next refresh fails.
Once the refresh token itself expires after 30 days, the user must sign in again through step 1.
Lifecycle at a glance
| Token | Lifetime | How to renew |
|---|---|---|
access_token | 1 day | Refresh-token grant (step 3) |
refresh_token | 30 days | Re-run the password grant (step 1) |
Errors
| Status | Error | What it means |
|---|---|---|
400 | invalid_grant | The user's email or password is wrong, or the refresh token has expired or already been used. |
401 | invalid_client | The client_id or client_secret is wrong. |
400 | unsupported_grant_type | The grant_type value is not password or refresh_token. |
Security
The password grant handles raw user credentials, so it is for trusted first-party clients only.
Never ship client_secret to a browser, mobile app or third party. For those, use the SSO / authorization-code flow instead.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | Get token (password grant) | Exchanges a user's email and password for an access token plus a refresh token, using the OAuth 2.0 Resource Owner Password Credentials grant. |
GET | Verify token | Confirm an access token is still valid and returns the context the caller needs to rehydrate a session: the authenticated user, their company, theme and white-label settings, and — for account users — plan context. |
POST | Refresh token | Exchanges a refresh token for a new access token and a new refresh token. |