Orange DOCS
Dashboard ↗
Authentication

Get a token, send it on every call

Orange uses short-lived JWT bearer tokens. You exchange a permanent API key/secret pair for a token, then attach that token to every request. Two steps, then you never touch your secret again until the token expires.

STEP 1 · once
Generate credentials
apiKey + apiSecret from the dashboard
›
STEP 2 · each session
Request a token
POST /token → JWT valid ~1 hr
›
EVERY REQUEST
Bearer header
Authorization: Bearer …

The token call

There's a single call — POST /token. Send the request below, get the response below. The endpoints further down show only the fields each step needs.

Request body
apiKey*
string
Your API key (public identifier)
apiSecret*
string
Your API secret (server-side only)
Response
token
string
JWT — send as a Bearer token on every call
expiry
number
Unix ms timestamp when the token expires

Generate your API credentials

Your apiKey and apiSecret are created once in the dashboard and reused to mint tokens.

  1. Sign in to the Orange dashboard.
  2. Open Settings → API Credentials.
  3. Click Generate New Credentials and store both values.
⚠️
The secret is shown once. Treat it like a password — store it server-side, never ship it in client code.
What you'll hold
🔑
apiKey
Public identifier, safe to log
🔒
apiSecret
Secret, server-side only
POST/token

Request a token

Send your credentials in the body. You get back a token and its expiry (Unix ms). No auth header on this call — it's how you get one.

Body parameters
apiKey*
string
Your API key
apiSecret*
string
Your API secret
POST /token 
curl -X POST \
  'https://api.app.useorange.com/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "your-api-key",
    "apiSecret": "your-api-secret"
  }'

Use the token

Attach it as a Bearer token in the Authorization header on every other endpoint.

💡
Cache the token and reuse it until expiry. Minting a new token on every request is unnecessary and rate-limited.
GET /merchants 
curl 'https://api.app.useorange.com/merchants' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

Expiry & rotation

◷

~1 hour lifespan

Tokens are valid for about an hour. Read the exact moment from expiry and refresh just before it.

🔄

Deploys rotate the secret

We ship often and regenerate the signing secret on each deploy, so a token can die early. Build for it: catch 401/403 and transparently re-auth.

Auth errors

Every error body is a bare { "message": "..." }. The status code tells you which call failed.

On POST /token
400
Bad request — apiKey or apiSecret missing/empty, or the key isn't recognised.
404
Not found — the apiSecret doesn't match the key.
On authenticated calls (returned by the authorizer)
401
Unauthorized — missing, malformed or expired Bearer token. Request a fresh one and retry.
403
Forbidden — token no longer valid against the current signing secret (often after a deploy rotates it). Re-authenticate.
4xxerror body
{
  "message": "API secret and key invalid"
}
Recommended pattern
Wrap calls so a 401/403 triggers one re-auth + retry before surfacing the error.