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 {{host}}/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
  }'

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    })

    resp, err := http.Post(
        "{{host}}/auth/refresh",
        "application/json",
        bytes.NewReader(body),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result struct {
        Success bool `json:"success"`
        Data    struct {
            AccessToken      string `json:"access_token"`
            RefreshToken     string `json:"refresh_token"`
            AccessExpiresAt  string `json:"access_expires_at"`
            RefreshExpiresAt string `json:"refresh_expires_at"`
            ClientID         int    `json:"client_id"`
        } `json:"data"`
    }
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Println("New Access Token:", result.Data.AccessToken)
}

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.

401 Unauthorized — Token is not valid.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Invalid refresh token"
  }
}

Returned when the JWT signature is invalid, the token does not exist in the system, or the token has been revoked.

401 Unauthorized — Token has expired.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Refresh token expired"
  }
}

Refresh tokens are valid for 7 days. After expiry, you must call login again.

401 Unauthorized — An access token was passed instead of a refresh token.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Invalid token type"
  }
}

Only refresh tokens (with sub: "refresh" claim) are accepted. Access tokens will be rejected.

403 Forbidden — Request IP is not in the client's whitelist.

{
  "error": {
    "name": "ForbiddenError",
    "code": "FORBIDDEN",
    "message": "IP address not authorized"
  }
}

Returned when the client has IP whitelist entries configured and the request IP does not match any allowed CIDR range.

POST /auth/refresh