Authentication

Every API call carries a token. Here's how to get one and how long it lasts. Send it on every protected call as an Authorization: Bearer <bearer-token> header.

Ways to obtain a token

1. Personal access token (recommended) — generate it on the dashboard's API Keys page (API Keys, then Manage token, then Generate token). It never expires, stays viewable on that page, and acts as the user who generated it. Regenerate at any time to rotate it — the previous token stops working immediately.
2. App credentials (OAuth 2.0) — a browser sign-in for apps that act on behalf of your own customers: they enter their password on our page, never in yours, and your server receives the token. Most partners don't need this.

If your integration authenticates with an email and password, it keeps working. New integrations should use a personal access token.

Signing users in to the dashboard with your identity provider (JumpCloud) is covered in Single sign-on; it doesn't give your app an API token.

Every token acts as the user behind it: an account user's token sees that account; a partner Owner or Admin token has partner-level access.

Using the token

Send it on every protected call:

Authorization: Bearer <bearer-token>

Token lifecycle

Tokens are OAuth 2.0 bearer tokens issued by our authorization server (RS256-signed JWTs).

• Personal access tokens do not expire — rotate them from the API Keys page (regenerating revokes the previous token immediately).
• App credentials (OAuth 2.0) access tokens last 1 day. Their refresh tokens last 30 days (see App credentials (OAuth 2.0) for the refresh call).
• Check any token with GET /verify-token — it returns the user and company while the token is valid, and 401 once it expires or is revoked.
• Revoke a token at any time (for example on sign-out) with GET /sso/revoking-token, sending the token as the Bearer header.

Locked accounts

Five wrong password attempts temporarily lock an account (starting at 1 minute and growing to a 15-minute maximum, lifting automatically). While locked, new sign-ins are refused; tokens issued earlier keep working until they expire or are revoked.

Public vs protected

Public (no token): POST /auth/discover, email OTP verification, the SSO redirect / callback / exchange legs, and the OAuth endpoints at the server root (/oauth/authorize, /oauth/token). Everything else requires a bearer token.

Before you begin

Create your app credentials (client_id + client_secret) on the dashboard's API Keys page — they are needed for App credentials (OAuth 2.0). The client secret is shown once, at creation. Personal access tokens need no app credentials.

Prerequisites

• A bearer token in the Authorization header. Any endpoint that needs no token says so on its own page.
• The id of each record the call targets. Every endpoint page lists the ids it needs.

Errors

Individual endpoints may return more; each page lists its own.

Sections

Endpoints