Authentication

The Octopus Cards API uses JWT (JSON Web Token) authentication. All protected endpoints require a valid access token in the Authorization header.

Auth Flow

POST /auth/login          →  Get access + refresh tokens
POST /auth/refresh        →  Exchange refresh token for a new pair
POST /auth/logout         →  Revoke all tokens for your client

Token Lifecycle

Using Tokens

Attach the access token as a Bearer token in the Authorization header on every request:

curl {{host}}/api/v1/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

IP Whitelisting

If your client has IP whitelist entries configured, requests are restricted to those CIDR ranges. This applies to login, refresh, and all protected endpoints.

If no whitelist is configured, all IPs are allowed.

Error Format

All auth errors follow this structure:

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials"
  }
}