Refresh Access Token

Exchanges a valid refresh token for a new access token and refresh token pair, extending the user's session without requiring them to re-enter their password.

Token rotation (security)
This endpoint implements single-use refresh tokens. When you call this endpoint:

The provided refresh_token is validated against the Redis session store.

A brand new access_token and refresh_token are generated.

The old refresh_token is immediately invalidated — it cannot be reused.

This means if an attacker steals a refresh token and uses it, the legitimate user's next refresh attempt will fail, alerting them to the potential compromise.

When to call this endpoint

Your client receives a 401 Unauthorized from any API endpoint (access token has expired).

Proactively when you detect the access token is near expiry (check expires_in from the login response).

If the refresh token is also expired
The user must re-authenticate via POST /oauth/token.

curl --location --request POST 'https://platform-oauth.convirza.com/oauth/refresh-token' \ --header 'Content-Type: application/json' \ --data-raw '{ "refresh_token": "xyz789refresh012345678901234567890" }'

{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbklkIjoiYWJjZDEyMzQtZWY1Ni03ODkwLWFiY2QtMTIzNDU2Nzg5MGFiIiwiaWF0IjoxNzA5NTU1NTU1LCJleHAiOjE3MDk1OTg3NTV9.xyz123", "frontend_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "refresh_token": "xyz789refresh012345678901234567890", "token_type": "Bearer", "expires_in": "2026-04-06T12:34:56.789Z", "refresh_expires_in": "2026-10-06T12:34:56.789Z", "user": { "user_id": 12345, "email": "user@example.com", "role_id": 2, "org_unit_id": 1001 } }

Refresh Access Token

Request

Responses