Using tokens

Sending the token

Every endpoint except the OAuth authorize and token endpoints and the direct sign-in and verify endpoints requires:

Authorization: Bearer <access_token>

The scheme is case-sensitive and must be followed by a single space and the token.

What the server checks

1. The header is present and well formed.
2. The token’s signature and expiry are valid.
3. The token is an access token. Refresh tokens and authorization codes are rejected even though they look similar.
4. The user the token was issued to still exists.

Tokens are self-contained and are not revoked when the OAuth client that issued them is deleted. They simply expire after 24 hours, and refreshing them fails once the client is gone.

Scopes are recorded on the token and echoed back by the token endpoint. They do not currently restrict which endpoints a token can call; every token has full access to the user’s own sites and controllers.

Failure responses

All are 401 with the standard envelope:

message	Cause
No authorization header	Header missing
Invalid authorization header format	Not Bearer <token>
Invalid token	Bad signature, expired, or not an access token
Invalid token claims	Malformed subject
User not found	Account no longer exists

A 500 with Failed to get user information is a temporary server-side failure; retry.

Tip

Branch on the HTTP status code rather than parsing the body of a 401 strictly.

Verifying a token you were given

If your backend receives a token from another component and wants to check it without calling a protected endpoint:

POST/api-gateway/v1/auth/verify

{ "token": "eyJhbGciOiJIUzI1NiIs..." }

{
  "status": "SUCCESS",
  "data": {
    "user": {
      "userId": 42,
      "userID": "aB3dE5fG7h",
      "email": "user@example.com",
      "username": "user@example.com",
      "role": "user",
      "iat": 1758400000,
      "exp": 1758486400
    }
  }
}

userID is the SplashMe account identifier, the same value as sub from the user info endpoint. exp is the expiry as a Unix timestamp. A missing token field returns 400 with No token provided. An invalid or expired token returns 401 with Invalid token, a malformed subject Invalid token claims, and a deleted account User not found.

Lifetimes at a glance

Token	Lifetime	Renewable
Authorization code	5 minutes, single use	No
Access token	24 hours	Via refresh token
Refresh token	30 days	A new one is issued on every refresh
Token from direct sign-in	24 hours	No refresh token; sign in again