Refresh a session

OpenAPI contract

Method

POST

Path

/api/v1/auth/refresh

Security

None

Response status

200 400 429 500

Request and response schemas

JSON

{
  "requestBody": {
    "application/json": {
      "$ref": "#/components/schemas/RefreshTokenRequest"
    }
  },
  "responses": {
    "200": {
      "description": "Session refreshed",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/AuthResponse"
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RequestError"
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

POST /api/v1/auth/refresh is public and accepts a nonblank refreshToken in JSON. It rotates the refresh token and returns a new access token, refresh token, token type, and access-token lifetime.

Replace the stored refresh token atomically: a refresh token is single-use after a successful rotation. An invalid, wrong-kind, expired, or replayed refresh token produces a session-invalid authentication error. Never send it to a third party.

http

POST /api/v1/auth/refresh
Content-Type: application/json