How to use refresh tokens

Refresh tokens let your integration renew access without sending user credentials again. They are optional and must be enabled on the application that authenticates the login.

See also: Versión en español

Enable refresh tokens

In the Betterez backoffice go to Administration → Integrations → Applications, open your application, and enable Use refresh tokens. Set the access token and refresh token durations as needed.

When disabled, access tokens last 2 days and login responses do not include a refreshToken.

When a refresh token is returned

If refresh tokens are enabled for the application, login responses may include a refreshToken field:

Login endpoint Typical use
POST /accounts/users Staff or backoffice users
POST /accounts/customers Customer login
POST /accounts/applications Application authentication

Use shortToken as the Bearer JWT for API requests, as described in How to use your JSON Web Token.

Store the refreshToken securely on your server. Do not expose it to client-side code when you can avoid it.

Redeem a refresh token

Call POST /accounts/refresh-token when the access token is about to expire or after receiving 401 on an authenticated request.

Only the application public key is required in the X-API-KEY header. Basic Auth is not used for this request.

curl --request POST \
  --url https://api.betterez.com/accounts/refresh-token \
  --header 'content-type: application/json' \
  --header 'x-api-key: {{x-api-key}}' \
  --data '{"refreshToken": "{{refresh-token}}"}'

On success the response matches the login endpoint that issued the token (user, customer, or application shape) and includes a new shortToken. When refresh tokens remain enabled, a new refreshToken is also returned.

Each refresh token is single-use. After a successful redeem, discard the old refresh token and store the new one.

Errors

HTTP Code Meaning
400 WRONG_DATA refreshToken is missing from the body
401 (header) Missing or invalid X-API-KEY
401 INVALID_REFRESH_TOKEN Token is invalid, expired, already used, or the subject can no longer sign in

When redeem fails, authenticate again with the original login endpoint.

Postman

Postman Collection

Postman Environment

Import both files, set your x-api-key, basicAuthToken, and audience in the environment, then run the requests in order.