POST /auth/refresh — Rotate your access token

Access tokens expire after 15 minutes. Instead of asking your users to log in again, you can silently obtain a fresh access token by sending your stored refresh token to this endpoint. The API validates the token, issues a new access token and a new refresh token, and immediately revokes the one you just used. This rotation strategy means a stolen refresh token can only be used once before it becomes invalid. No authentication header is required — the refresh token itself is the credential.

Endpoint

POST https://api.dubupay.com/api/v1/auth/refresh

Request body

string

required

The refresh token previously issued by POST /auth/login, POST /auth/refresh, or POST /auth/verify-email. Each refresh token can only be used once.

Response

HTTP 200 OK on success.

boolean

true on a successful token rotation.

object

Show data

string

A new JWT access token. Valid for 15 minutes.

string

A new JWT refresh token. Valid for 7 days. Replace the token you stored with this new value immediately — the previous refresh token is now invalid and cannot be used again.

Example

curl -X POST https://api.dubupay.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Token rotation

Every successful call to this endpoint invalidates the refresh token you submitted and replaces it with a brand-new one. You must update your stored refresh token after every rotation. If the same refresh token is used twice — for example because an attacker replayed a captured token — the second attempt returns 401 TOKEN_REVOKED. At that point you should treat the session as compromised, clear all stored tokens, and require the user to log in again. Refresh tokens are also invalidated when you:

Call POST /auth/logout
Change your password via PATCH /auth/me/password

In both cases any stored refresh token becomes immediately unusable and a new login is required.

Error responses

Status	Code	Description
`400`	Validation error	`refresh_token` is missing from the request body.
`401`	`INVALID_REFRESH_TOKEN`	The token is malformed, has expired, or the signature does not match.
`401`	`TOKEN_REVOKED`	The token was already used or has been invalidated (logout / password change).
`401`	`UNAUTHORIZED`	The merchant account associated with this token no longer exists or is deactivated.

Overview

Auth

Payments

Trading

Commerce

Webhooks

POST /auth/refresh — Rotate your access token

Endpoint

Request body

Response

Example

Token rotation

Error responses