Sign in

v1

latestOpenAPI 3.0.02026-08-04891301.4 MB
auth

Exchange a one-time login token for session tokens

Consumes a single-use login token delivered via email and returns an access token, refresh token, and the authenticated user object. One-time tokens are issued by the passwordless login flow and expire after a short window; submitting an expired or already-used token returns HTTP 401.

If timezone is provided and the user's current timezone is still the default ("America/Los_Angeles"), the account timezone is updated in the same request. Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.

post/api/v1/auth/token

Request body

timezonestring

IANA timezone name to apply to the account if the account timezone is still the default, e.g. "Europe/London". Omit to leave the timezone unchanged.

tokenstring required

Single-use login token extracted from the magic link or email code flow.

Example request

{
  "timezone": "America/New_York",
  "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"
  }
}