Refresh Token

`POST /auth/refresh`

Exchange a valid refresh token for a new access/refresh token pair. The old refresh token is revoked after a successful refresh.

Request

curl -X POST https://api.octopuscards.io/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

Request Parameters

Key	Type	Required	Description
`refresh_token`	string	Yes	A valid, non-expired refresh token obtained from login or a previous refresh

Response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "access_expires_at": "2025-01-15T14:00:00Z",
    "refresh_expires_at": "2025-01-22T13:00:00Z",
    "client_id": 42
  }
}

The response schema is identical to the login endpoint.

Response Fields

Key	Type	Description
`success`	boolean	Always `true` on success
`data.access_token`	string	New JWT access token. Valid for 1 hour.
`data.refresh_token`	string	New JWT refresh token. Valid for 7 days. The previous refresh token is revoked.
`data.access_expires_at`	string	ISO 8601 expiry timestamp for the new access token
`data.refresh_expires_at`	string	ISO 8601 expiry timestamp for the new refresh token
`data.client_id`	integer	Your client ID

Token Rotation

After a successful refresh:

The old refresh token is revoked and cannot be reused
A new access token (1 hour) and refresh token (7 days) are issued
Store the new refresh token - the old one will return 401 if used again

Errors

400 Bad Request - Refresh token not provided.

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "Refresh token is required"
  }
}

Returned when the refresh_token field is empty or missing.

POST /auth/refresh