Skip to navigation
Get started

Authentication

Exchange credentials for a JWT, then send it as a Bearer token.
View as Markdown

Every 52 Cloud API call is authenticated with an access token issued by the Auth API at https://auth.fiftytwo.com.

There are two tokens:

TokenLifetimePurpose
Access token (AT)~24 hoursSent on every API request
Refresh token (RT)~30 daysExchanged for a new AT without re-authenticating

Both are JWTs carrying an exp claim (a Unix timestamp), so you can read the exact expiry without calling the API.

Sign in

curl -X POST https://auth.fiftytwo.com/v1/user \
  -H "Content-Type: application/json" \
  -d '{
    "username": "integration@example.com",
    "password": "YOUR_PASSWORD"
  }'

A 200 returns both tokens:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use the token

Send the access token on every request:

curl https://api.fiftytwo.com/masterdata/articles/v1/chain/1/5701234000019 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Refresh, don’t re-sign-in

Sign-in is rate limited to 15 requests per 60 seconds. Calling /v1/user before every API request will get you 429 Too Many Requests. Cache the access token for its full lifetime.

When a call returns 401, exchange the token pair for a fresh one:

curl -X POST https://auth.fiftytwo.com/v1/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "accessToken": "EXPIRED_ACCESS_TOKEN",
    "refreshToken": "VALID_REFRESH_TOKEN"
  }'

Both tokens must belong to the same session. If the refresh fails, sign in again with /v1/user.

1

Sign in once

POST /v1/user. Store both tokens somewhere your whole integration can read them, not per-process, or every worker will burn a sign-in.

2

Read exp from the access token

Decode the JWT payload and refresh a few minutes before it expires. This avoids the 401 round trip entirely.

3

Treat 401 as 'refresh, then retry once'

If you would rather react than predict: on 401, call /v1/refresh, then replay the original request exactly once.

4

Fall back to sign-in

If the refresh also fails, the session is gone. Sign in again, and make sure only one process does, or you will hit the sign-in rate limit.

A 401 does not always mean “expired”. It can also mean the account lacks privileges for that endpoint. If refreshing succeeds but the call still returns 401, check the account’s permissions rather than retrying.

Register Sale is different

The Register Sale API authenticates with an Auth0-issued Bearer JWT rather than a token from auth.fiftytwo.com. The header looks identical; the issuer does not. Ask your FiftyTwo consultant which tenant issues tokens for your integration.