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 a team or staff invitation.
On this page
Endpoints#
34 operations, each with its parameters, schemas and an example request on its own page.
- postAccept invitation/api/auth/accept-invitationJoins a workspace and signs in, in one step.
- postAccept a staff invitation/api/auth/accept-staff-invitationTakes up staff access and signs in, in one step.
- postChange password/api/auth/change-password
- postForgot password/api/auth/forgot-passwordStarts a password reset.
- postComplete Google sign-in/api/auth/googleExchanges a Google authorization code for a session on this platform.
- getStart Google sign-in/api/auth/google/startEverything the browser needs to begin a Google sign-in.
- getList identities/api/auth/identitiesWhich sign-in methods this account has.
- deleteUnlink identity/api/auth/identities/{provider}Disconnects a provider, unless it is the only way into the account.
- getPreview invitation/api/auth/invitationWhat the acceptance page may show before anybody has signed in.
- postLog in/api/auth/loginVerifies a password, and issues tokens only if that is the whole story.
- postLog out/api/auth/logout
- postLog out everywhere/api/auth/logout-all
- getGet the current user/api/auth/me
- getMFA status/api/auth/mfa
- postActivate MFA/api/auth/mfa/activateProves the authenticator works, then switches the factor on.
- postDisable MFA/api/auth/mfa/disableTurns the second factor off. Needs the password and a current code.
- postRegenerate recovery codes/api/auth/mfa/recovery-codesIssues a fresh set and invalidates every previous one.
- postSetup MFA/api/auth/mfa/setupGenerates a secret. Does not switch the factor on.
- postVerify MFA/api/auth/mfa/verifyCompletes a sign-in that stopped at the second factor.
- getList my organizations/api/auth/organizations
- postRequest OTP/api/auth/otp/requestEmails a six-digit code.
- postVerify OTP/api/auth/otp/verifyExchanges a correct code for a session.
- postRefresh a session/api/auth/refreshExchanges a refresh token for a new pair.
- postRegister an account/api/auth/registerCreates a user, their workspace and an owner membership, then signs them in.
- postResend verification/api/auth/resend-verificationSends a fresh activation link.
- postReset password/api/auth/reset-passwordCompletes a password reset.
- getMy sessions/api/auth/sessionsWhere this account is signed in. current marks this device.
- deleteEnd my session/api/auth/sessions/{session_id}Signs one of this account's other devices out, immediately.
- getPreview a staff invitation/api/auth/staff-invitationThe terms of the offer, for the acceptance page.
- postEnter support session/api/auth/support/enterStarts working inside a customer's workspace, from the admin console.
- postExit support session/api/auth/support/exitEnds the support session this browser holds, and drops the cookie.
- postSwitch organization/api/auth/switch-organizationMoves this session into another workspace.
- getVerification status/api/auth/verification-status
- postVerify email/api/auth/verify-emailConfirms an address from the link in the activation email.
Authentication#
16 of 34 calls need Authorization: Bearer — see Authentication. These work without one: accept invitation, accept a staff 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, preview a staff invitation, exit support session and verify email.
Objects returned#
The models these endpoints send back, with every field. Open one to read it.
TokenResponse7 fields
access_tokenstringrequiredexpires_inintegerrequiredorganizationOrgReadrequired10 fieldsOrgRead
idstringrequirednamestringrequiredplan_tierstringrequiredroleOrgRole | stringrequiredslugstringrequiredaccessstringOne of: member, agency·Default: member
is_activebooleanDefault: true
is_currentbooleanDefault: false
is_defaultbooleanDefault: false
parent_org_idstring | null
userUserReadrequired9 fieldsUserRead
created_atstring (date-time)requiredemailstringrequiredfull_namestringrequiredidstringrequiredis_activebooleanrequiredis_verifiedbooleanrequiredavatar_urlstring | nullis_staffbooleanDefault: false
staff_levelstring | nullOne of: view, edit, owner
refresh_tokenstring | nullsupportSupportSessionInfo | nullPresent on a token issued inside a staff support session.
What the customer surfaces need to draw the banner that says so - whose workspace, whether changes are allowed, and when it ends by itself.
5 fieldsSupportSessionInfo
expires_atstring (date-time)requiredorg_idstringrequiredorg_namestringrequiredsession_idstringrequiredwritebooleanrequired
token_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
UserRead9 fields
created_atstring (date-time)requiredemailstringrequiredfull_namestringrequiredidstringrequiredis_activebooleanrequiredis_verifiedbooleanrequiredavatar_urlstring | nullis_staffbooleanDefault: false
staff_levelstring | nullOne of: view, edit, owner
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
OrgRead10 fields
idstringrequirednamestringrequiredplan_tierstringrequiredroleOrgRole | stringrequiredslugstringrequiredaccessstringOne of: member, agency·Default: member
is_activebooleanDefault: true
is_currentbooleanDefault: false
is_defaultbooleanDefault: false
parent_org_idstring | null
Something unclear or missing? Tell us and we’ll fix it.