Skip to main content
Everything you need to start calling the API — the base URL and how to authenticate. Every other guide assumes what’s on this page.

​
Base URL

All API requests go to:
Endpoint paths throughout these guides are relative to this base.
The API uses JWT bearer tokens: exchange your credentials for an access token, send it on every request, and refresh it when it expires.

​
How it works

  • Access token — valid for 24 hours. Sent on every request as a bearer token.
  • Refresh token — valid for 7 days. Used to mint new access tokens without sending credentials again.
Both come back from a single login call. A typical integration logs in once, caches the tokens, and refreshes the access token each day until the refresh token expires.

​
1. Get a token

POST your credentials to the token endpoint. It returns an access and a refresh token.
If the account has 2FA enabled, add a current otp — see Two-factor authentication. → login in the API reference

​
2. Authenticate every request

Send the access token in the Authorization header on every call. Every endpoint requires it.
A missing or invalid token returns 401.

​
3. Refresh when it expires

Access tokens are valid for 24 hours. When one expires, a request returns 401 — exchange your refresh token for a new access token instead of logging in again.
After 7 days the refresh token expires too; then log in again (step 1). → token_refresh in the API reference

​
Two-factor authentication

If an account has 2FA enabled, the login call requires a current TOTP code in the otp field:
To enable 2FA on an account:
1

Start enrollment

setup_2fa returns a seed and a qr_code_url. Add it to your authenticator app.
2

Confirm

verify_2fa_enrollment with a current otp activates 2FA and returns backup codes — store them securely.
For system integrations, use a dedicated service account. If that account has 2FA enabled, your integration must generate the current TOTP code at login — so many teams keep 2FA off for machine accounts and protect the credentials another way.

​
Best practices for integrations

  • Use a dedicated service account, not a person’s login.
  • Store credentials in a secret manager — never in code or version control.
  • Cache the access token and reuse it; refresh on 401, re-authenticate only when refresh fails.
  • Send Authorization: Bearer <access> on every request.

​
Change a password

new_password updates the password for the authenticated account (password, new_password, confirm_new_password).

​
Endpoints