API reference
Auth API
Accounts and sessions: registration and email verification, password and one-time-code sign-in, Google sign-in, multi-factor authentication, linked identities and accepting an invitation.
Endpoints
27 operations, each with its parameters, schemas and an example request on its own page.
- post/api/auth/accept-invitationAccept invitation — Joins a workspace and signs in, in one step.
- post/api/auth/change-passwordChange password
- post/api/auth/forgot-passwordForgot password — Starts a password reset.
- post/api/auth/googleComplete Google sign-in — Exchanges a Google authorization code for a session on this platform.
- get/api/auth/google/startStart Google sign-in — Everything the browser needs to begin a Google sign-in.
- get/api/auth/identitiesList identities — Which sign-in methods this account has.
- delete/api/auth/identities/{provider}Unlink identity — Disconnects a provider, unless it is the only way into the account.
- get/api/auth/invitationPreview invitation — What the acceptance page may show before anybody has signed in.
- post/api/auth/loginLog in — Verifies a password, and issues tokens only if that is the whole story.
- post/api/auth/logoutLog out
- post/api/auth/logout-allLog out everywhere
- get/api/auth/meGet the current user
- get/api/auth/mfaMFA status
- post/api/auth/mfa/activateActivate MFA — Proves the authenticator works, then switches the factor on.
- post/api/auth/mfa/disableDisable MFA — Turns the second factor off. Needs the password and a current code.
- post/api/auth/mfa/recovery-codesRegenerate recovery codes — Issues a fresh set and invalidates every previous one.
- post/api/auth/mfa/setupSetup MFA — Generates a secret. Does not switch the factor on.
- post/api/auth/mfa/verifyVerify MFA — Completes a sign-in that stopped at the second factor.
- get/api/auth/organizationsList my organizations
- post/api/auth/otp/requestRequest OTP — Emails a six-digit code.
- post/api/auth/otp/verifyVerify OTP — Exchanges a correct code for a session.
- post/api/auth/refreshRefresh a session — Exchanges a refresh token for a new pair.
- post/api/auth/registerRegister an account — Creates a user, their workspace and an owner membership, then signs them in.
- post/api/auth/resend-verificationResend verification — Sends a fresh activation link.
- post/api/auth/reset-passwordReset password — Completes a password reset.
- get/api/auth/verification-statusVerification status
- post/api/auth/verify-emailVerify email — Confirms an address from the link in the activation email.
Authentication
12 of 27 calls need Authorization: Bearer — see Authentication. These work without one: accept invitation, forgot password, complete google sign-in, start google sign-in, preview invitation, log in, log out, verify mfa, request otp, verify otp, refresh a session, register an account, resend verification, reset password and verify email.
Objects returned
The models these endpoints send back, with every field. Open one to read it.
TokenResponse6 fields
access_tokenstringrequiredexpires_inintegerrequiredorganizationOrgReadrequired7 fields · OrgRead
idstringrequirednamestringrequiredplan_tierstringrequiredroleOrgRole | stringrequiredslugstringrequiredis_defaultbooleanDefault: false
parent_org_idstring | null
userUserReadrequired7 fields · UserRead
created_atstring (date-time)requiredemailstringrequiredfull_namestringrequiredidstringrequiredis_activebooleanrequiredis_verifiedbooleanrequiredavatar_urlstring | null
refresh_tokenstring | nulltoken_typestringDefault: bearer
Message2 fields
messagestringrequiredokbooleanDefault: true
GoogleStartResponse5 fields
authorization_urlstringrequiredcode_verifierstringrequirednoncestringrequiredredirect_uristringrequiredstatestringrequired
IdentityRead4 fields
created_atstring (date-time)requiredproviderstringrequiredemailstring | nulllast_login_atstring (date-time) | null
InvitationPreview7 fields
emailstringrequiredexpires_atstring (date-time)requiredorganization_namestringrequiredorganization_slugstringrequiredroleOrgRole | stringrequiredhas_accountbooleanDefault: false
invited_bystring | null
UserRead7 fields
created_atstring (date-time)requiredemailstringrequiredfull_namestringrequiredidstringrequiredis_activebooleanrequiredis_verifiedbooleanrequiredavatar_urlstring | null
MfaStatus5 fields
enabledbooleanrequiredactivated_atstring (date-time) | nullpendingbooleanDefault: false
recovery_codes_remainingintegerDefault: 0
recovery_generated_atstring (date-time) | null
MfaCodesResponse2 fields
generated_atstring (date-time)requiredrecovery_codesarray of stringrequired
MfaSetupResponse5 fields
digitsintegerrequiredmanual_keystringrequiredperiod_secondsintegerrequiredsecretstringrequireduristringrequired
OrgRead7 fields
idstringrequirednamestringrequiredplan_tierstringrequiredroleOrgRole | stringrequiredslugstringrequiredis_defaultbooleanDefault: false
parent_org_idstring | null
Something here wrong or missing? Tell us — the documentation and the API are maintained by the same person, so a correction is a fix rather than a ticket.