Auth API

End-user authentication (signup, login, OAuth, MFA)

REST API endpoints for Auth. 29 operations.

Sign in anonymously

plaintext

POST /v1/auth/anonymous

Creates an anonymous end-user account and returns auth tokens; the account can later be linked to a real identity via identity linking.

Auth: Bearer API key

Responses

Status	Description
`201`	Anonymous account created
`401`	Missing or invalid API key
`500`	Internal error

operationId: signUpAnonymous

Link an identity

plaintext

POST /v1/auth/identity/link

Links an additional identity (e.g. an OAuth provider or email/password) to the authenticated user, including upgrading anonymous accounts.

Auth: Bearer API key

Responses

Status	Description
`200`	Identity linked
`401`	Missing or invalid API key
`500`	Internal error

operationId: linkIdentity

Log in

plaintext

POST /v1/auth/login

Authenticates an end user with email and password and returns auth tokens.

Auth: Bearer API key

Request body

application/json (required) — schema SignInRequest.

Responses

Status	Description
`200`	Login successful
`401`	Invalid credentials
`423`	Account locked due to too many failed attempts
`500`	Internal error

operationId: login

Log out

plaintext

POST /v1/auth/logout

Invalidates the caller's current session/token.

Auth: Bearer API key

Responses

Status	Description
`200`	Logged out
`401`	Missing or invalid API key
`500`	Internal error

operationId: logout

Send a magic link

plaintext

POST /v1/auth/magic-link

Emails the user a passwordless magic sign-in link.

Auth: Bearer API key

Responses

Status	Description
`200`	Magic link sent
`401`	Missing or invalid API key
`500`	Internal error

operationId: sendMagicLink

Verify a magic link

plaintext

POST /v1/auth/magic-link/verify

Exchanges the emailed magic-link token for Scalix auth tokens.

Auth: Bearer API key

Responses

Status	Description
`200`	Auth tokens
`401`	Missing or invalid API key
`500`	Internal error

operationId: verifyMagicLink

List the user's organizations

plaintext

GET /v1/auth/me/orgs

Returns the organizations the authenticated end user belongs to.

Auth: Bearer API key

Responses

Status	Description
`200`	Organizations for the current user
`401`	Missing or invalid API key
`500`	Internal error

operationId: listUserOrgs

Complete an MFA challenge

plaintext

POST /v1/auth/mfa/challenge

Verifies a TOTP code against an enrolled factor during sign-in and returns auth tokens.

Auth: Bearer API key

Responses

Status	Description
`200`	Auth tokens
`401`	Missing or invalid API key
`500`	Internal error

operationId: challengeMfa

Enroll in MFA

plaintext

POST /v1/auth/mfa/enroll

Begins TOTP multi-factor enrollment and returns the secret and QR code.

Auth: Bearer API key

Responses

Status	Description
`200`	MFA enrollment data (TOTP secret, QR code)
`401`	Missing or invalid API key
`500`	Internal error

operationId: enrollMfa

List MFA factors

plaintext

GET /v1/auth/mfa/factors

Returns the authenticated user's enrolled multi-factor authentication factors.

Auth: Bearer API key

Responses

Status	Description
`200`	Enrolled MFA factors
`401`	Missing or invalid API key
`500`	Internal error

operationId: listMfaFactors

Delete an MFA factor

plaintext

DELETE /v1/auth/mfa/factors/{id}

Removes an enrolled multi-factor authentication factor.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	MFA factor id

Responses

Status	Description
`204`	Factor deleted
`401`	Missing or invalid API key
`500`	Internal error

operationId: deleteMfaFactor

Verify MFA

plaintext

POST /v1/auth/mfa/verify

Verifies a TOTP code to complete multi-factor enrollment or a challenge.

Auth: Bearer API key

Responses

Status	Description
`200`	MFA verified
`401`	Missing or invalid API key
`500`	Internal error

operationId: verifyMfa

Start OAuth authorization

plaintext

POST /v1/auth/oauth/authorize

Returns the provider authorization URL to begin an OAuth sign-in flow.

Auth: Bearer API key

Responses

Status	Description
`200`	Authorization URL
`401`	Missing or invalid API key
`500`	Internal error

operationId: authorizeOauth

Complete OAuth sign-in

plaintext

POST /v1/auth/oauth/callback

Exchanges the provider OAuth callback for Scalix auth tokens.

Auth: Bearer API key

Responses

Status	Description
`200`	Auth tokens
`401`	Missing or invalid API key
`500`	Internal error

operationId: oauthCallback

Send a one-time passcode

plaintext

POST /v1/auth/otp

Sends the user a one-time passcode for passwordless sign-in.

Auth: Bearer API key

Responses

Status	Description
`200`	OTP sent
`401`	Missing or invalid API key
`500`	Internal error

operationId: sendOtp

Verify a one-time passcode

plaintext

POST /v1/auth/otp/verify

Exchanges the phone number and OTP code for Scalix auth tokens.

Auth: Bearer API key

Responses

Status	Description
`200`	Auth tokens
`401`	Missing or invalid API key
`500`	Internal error

operationId: verifyOtp

Request a password reset

plaintext

POST /v1/auth/recover

Emails the user a password-recovery link.

Auth: Bearer API key

Responses

Status	Description
`200`	Recovery email sent
`401`	Missing or invalid API key
`500`	Internal error

operationId: requestPasswordReset

Reset the password

plaintext

PUT /v1/auth/recover/reset

Sets a new password using a recovery token.

Auth: Bearer API key

Responses

Status	Description
`200`	Password updated
`401`	Missing or invalid API key
`500`	Internal error

operationId: resetPassword

Refresh auth tokens

plaintext

POST /v1/auth/refresh

Exchanges a refresh token for a new access/refresh token pair.

Auth: Bearer API key

Responses

Status	Description
`200`	New tokens
`401`	Missing or invalid API key
`500`	Internal error

operationId: refreshToken

Resend the verification email

plaintext

POST /v1/auth/resend-verification

Sends the email-verification message again.

Auth: Bearer API key

Responses

Status	Description
`200`	Verification email sent
`401`	Missing or invalid API key
`500`	Internal error

operationId: resendVerification

List sessions

plaintext

GET /v1/auth/sessions

Returns the authenticated user's active sessions.

Auth: Bearer API key

Responses

Status	Description
`200`	Active sessions
`401`	Missing or invalid API key
`500`	Internal error

operationId: listSessions

Revoke a session

plaintext

DELETE /v1/auth/sessions/{id}

Terminates one of the authenticated user's sessions.

Auth: Bearer API key

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Session id

Responses

Status	Description
`204`	Session revoked
`401`	Missing or invalid API key
`500`	Internal error

operationId: revokeSession

Sign up a new user

plaintext

POST /v1/auth/signup

Creates a new end-user account and returns auth tokens plus the created user.

Auth: Bearer API key

Request body

application/json (required) — schema SignUpRequest.

Responses

Status	Description
`201`	Account created
`401`	Missing or invalid API key
`409`	Email already exists
`429`	Too many signups from this IP
`500`	Internal error

operationId: signUp

Get the current user

plaintext

GET /v1/auth/user

Returns the authenticated end user's profile.

Auth: Bearer API key

Responses

Status	Description
`200`	User profile
`401`	Missing or invalid API key
`500`	Internal error

operationId: getAuthUser

Update the current user

plaintext

PUT /v1/auth/user

Updates the authenticated end user's profile and returns the new record.

Auth: Bearer API key

Responses

Status	Description
`200`	Updated user
`401`	Missing or invalid API key
`500`	Internal error

operationId: updateAuthUser

List consent records

plaintext

GET /v1/auth/user/consent

Returns the authenticated user's consent audit trail.

Auth: Bearer API key

Responses

Status	Description
`200`	Consent audit trail
`401`	Missing or invalid API key
`500`	Internal error

operationId: listAuthUserConsent

Record a consent decision

plaintext

POST /v1/auth/user/consent

Records a single GDPR consent decision for the authenticated user.

Auth: Bearer API key

Request body

application/json (required) — schema RecordConsentRequest.

Responses

Status	Description
`201`	Consent recorded
`401`	Missing or invalid API key
`500`	Internal error

operationId: recordAuthUserConsent

Export user data

plaintext

GET /v1/auth/user/export

Returns a complete export of the authenticated user's data (GDPR portability).

Auth: Bearer API key

Responses

Status	Description
`200`	Complete user data export
`401`	Missing or invalid API key
`500`	Internal error

operationId: exportAuthUser

Verify an email address

plaintext

POST /v1/auth/verify

Confirms the user's email address using the emailed verification token.

Auth: Bearer API key

Responses

Status	Description
`200`	Email verified
`401`	Missing or invalid API key
`500`	Internal error

operationId: verifyEmail