Sign in

v1

latestOpenAPI 3.0.02026-08-04891301.4 MB
auth

Refresh an access token

Exchanges a valid refresh token for a new access token and a new refresh token, rotating the refresh token on every call. The response also includes the updated user object. Store the new refresh token and discard the old one.

Refresh tokens are single-use — submitting an already-consumed token returns HTTP 401. Rate limiting is applied per (user, IP) pair when the token can be verified, and falls back to IP-only when it cannot. The limit is 30 exchanges per minute per bucket; exceeding it returns HTTP 429.

post/api/v1/auth/refresh

Request body

refresh_tokenstring required

Refresh token previously issued by a login, registration, or token-refresh response.

Example request

{
  "refresh_token": "string"
}

Response

Successful response

expires_ininteger required

Number of seconds until token expires. After this period, use refresh_token to obtain a new access token.

metadataobject

Optional auxiliary data associated with this authentication event, such as onboarding_job_id when the user is completing onboarding. null when no extra context is present.

refresh_tokenstring required

Long-lived opaque refresh token. Use this to obtain a new access token when token expires.

tokenstring required

Short-lived JWT access token. Include this value in the Authorization: Bearer <token> header for all authenticated API requests.

token_typestring required

Token scheme. Always "Bearer".

Example response

{
  "expires_in": 3600,
  "metadata": {
    "key": "value"
  },
  "refresh_token": "rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "user": {
    "alias": "jdoe",
    "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
    "app_name": "Example Name",
    "email": "user@example.com",
    "id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
    "is_system_user": true,
    "metadata": {
      "key": "value"
    },
    "name": "Example Name",
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "org_name": "Example Name",
    "org_role": "member",
    "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
    "sandbox_name": "Example Name"
  }
}