Reference
API reference
Every endpoint your backend can call, what it takes and what it answers.
All under /v1, with X-Api-Key unless noted. Each endpoint links to the page that explains it; errors are on Errors and rate limits.
Sign-in and accounts
- POST
/oauth/register- Send
- appId, email, password
- Returns
- 200 { accessToken, refreshToken }
- POST
/oauth/login- Send
- appId, email, password
- Returns
- 200 tokens, or 202 { requiresMfa, mfaToken }
- POST
/oauth/verify-mfa- Send
- appId, mfaToken, mfaCode
- Returns
- 200 tokens
- POST
/oauth/refresh-token- Send
- appId, refreshToken
- Returns
- 200 tokens (a new refresh token)
- POST
/oauth/logout- Send
- refreshToken
- Returns
- 204
- POST
/oauth/exchange- Send
- connectionToken
- Returns
- 200 tokens
- POST
/oauth/sso-exchange- Send
- appId, email
- Returns
- 200 tokens
- POST
/oauth/users/import- Send
- appId, email, legacyPasswordHash?, emailVerified, createdAt?
- Returns
- 200 { userId, created }
- POST
/oauth/change-password- Send
- appId, email, currentPassword?, newPassword
- Returns
- 204
- DELETE
/oauth/account- Send
- ?appId&email
- Returns
- 204
- POST
/oauth/request-email-verification- Send
- appId, email, subject, htmlTemplate
- Returns
- 200
- POST
/oauth/verify-email- Send
- appId, email, codeOrToken
- Returns
- 200
- POST
/oauth/request-password-reset- Send
- appId, email, subject, htmlTemplate
- Returns
- 200
- POST
/oauth/verify-password-reset-code- Send
- appId, email, code
- Returns
- 200 { token }
- POST
/oauth/reset-password- Send
- appId, token, newPassword
- Returns
- 200
- POST
/oauth/mfa/setup- Send
- appId, email
- Returns
- 200 { secretKey, qrCodeUri }
- POST
/oauth/mfa/verify-setup- Send
- appId, email, base32Secret, verificationCode
- Returns
- 204
- POST
/oauth/mfa/disable- Send
- appId, email, password
- Returns
- 204
- GET
/oauth/sessions- Send
- ?appId&email¤tToken&page&pageSize&search
- Returns
- 200 { items, page, pageSize, totalCount, hasNextPage, hasPreviousPage }
- DELETE
/oauth/sessions/{sessionId}- Send
- ?appId&email
- Returns
- 204
- GET
/oauth/google/url- Send
- ?appId&redirectUrl (no key)
- Returns
- 200 { url }
- GET
/oauth/google/callback- Send
- ?code&state (from Google)
- Returns
- 302 to your callback with connectionToken
register, login, verify-mfa, refresh-token, exchange and sso-exchange answer access tokens signed RS256 with your app's own key: see Verifying access tokens.
Session items are { id, deviceName, browser, os, ipAddress, isCurrentSession, lastActive, startedAt, appName }.
Platforms and tenants
- GET
/platform/tenants- Send
- ?parentAppId&cursor&limit
- Returns
- 200 { items, nextCursor, hasMore }
- POST
/platform/tenants- Send
- parentAppId, name, homepageUrl, allowedCallbackUrls?
- Returns
- 200 { childAppId, apiKey }
- PUT
/platform/tenants/{id}- Send
- parentAppId, name, description, homepageUrl
- Returns
- 204
- DELETE
/platform/tenants/{id}- Send
- ?parentAppId
- Returns
- 204
- PUT
/platform/tenants/{id}/token-settings- Send
- ?parentAppId, body maxActiveSessions
- Returns
- 204
- POST
/platform/tenants/{id}/callbacks- Send
- url
- Returns
- 204
Public keys
At the root of the API, not under /v1, and without a key: they are public.
- GET
/apps/{appId}/.well-known/jwks.json- Send
- nothing
- Returns
- 200 { keys: [{ kty, use, alg, kid, n, e }] }, 404 for an unknown app
- GET
/apps/{appId}/.well-known/openid-configuration- Send
- nothing
- Returns
- 200 { issuer, jwks_uri, claims_supported }