Authentication API
Reference for the Authentication endpoint group — 11 endpoints.
Generated from the live OpenAPI spec. Re-run _generate_api_reference.py after backend changes.
Authentication#
All endpoints require a Bearer JWT in the Authorization header unless noted otherwise. See Concepts → Tokens and scopes and Reference → OAuth endpoints for how to obtain one.
Endpoints#
POST /api/v1/auth/tenants/{tenant_slug}/forgot-password#
Forgot Password
Initiate password reset flow.
Sends password reset email to the user.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→ForgotPasswordRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/login#
Login
Direct login endpoint for hosted login page.
Returns MFA challenge if MFA is required, otherwise creates session and tokens.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→scaikey__schemas__auth__LoginRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_LoginResponse_ |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/mfa/challenge#
Begin Mfa Challenge
Begin an MFA challenge for the chosen method.
Returns {challenge_id, options?}. options is set only for WebAuthn
and contains the credential request options the browser passes to
navigator.credentials.get().
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→MFAChallengeBeginRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/mfa/email/send#
Send Email Mfa
Send MFA code via email.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
mfa_token |
query | yes | string |
|
user_id |
query | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/mfa/verify#
Verify Mfa
Verify MFA challenge.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→MFAChallengeRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_MFAChallengeResponse_ |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/mfa/webauthn/begin#
Begin Webauthn Auth
Begin WebAuthn authentication challenge.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
mfa_token |
query | yes | string |
|
user_id |
query | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/password/forgot#
Forgot Password
Initiate password reset flow.
Sends password reset email to the user.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→ForgotPasswordRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/password/reset#
Reset Password
Complete a password reset with a token issued by /forgot-password.
Validates the single-use token, sets the new password, and logs the user out
everywhere (sessions terminated, refresh tokens revoked). Error bodies use the
{"error": {"code", "message"}} shape the auth SPA parses, so the reset
form can distinguish an expired link from other failures.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→ResetPasswordRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/register#
Register
Self-registration endpoint.
Creates a new user account (if self-registration is enabled for tenant).
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→RegisterRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_RegisterResponse_ |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/tenants/{tenant_slug}/reset-password#
Reset Password
Complete a password reset with a token issued by /forgot-password.
Validates the single-use token, sets the new password, and logs the user out
everywhere (sessions terminated, refresh tokens revoked). Error bodies use the
{"error": {"code", "message"}} shape the auth SPA parses, so the reset
form can distinguish an expired link from other failures.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
Request body:
Required.
application/json→ResetPasswordRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/auth/tenants/{tenant_slug}/verify-email#
Verify Email
Verify email address with token from email.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_slug |
path | yes | string |
|
token |
query | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
Schemas#
Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.
ApiResponse_LoginResponse_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
scaikey__schemas__auth__LoginResponse |
yes | |
meta |
MetaResponse |
no |
ApiResponse_MFAChallengeResponse_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
MFAChallengeResponse |
yes | |
meta |
MetaResponse |
no |
ApiResponse_RegisterResponse_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
RegisterResponse |
yes | |
meta |
MetaResponse |
no |
ForgotPasswordRequest#
Forgot password request.
Both purposes mint the same single-use token row and the same
reset URL — the only difference is the email's subject and copy.
welcome is intended for ScaiControl-style pre-create flows
where the user has just signed up and an email saying "reset your
password" reads as if something broke. Add new purpose values
in :func:scaikey.services.email.send_password_reset and surface
them here.
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
yes | |
redirect_uri |
string | null |
no | |
purpose |
string |
no | Selects the email template variant. reset (default) matches today's wording. welcome swaps to first-time-user copy intended for pre-created accounts whose owner is choosing their password for the first time. |
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
MFAChallengeBeginRequest#
Body for the unified MFA challenge endpoint.
The frontend dispatches challenge requests for EMAIL and WEBAUTHN
through this one endpoint; the backend routes to the right service
method based on method. TOTP and BACKUP_CODE don't need a
server-issued challenge — they're user-provided codes — so they're
not accepted here.
| Field | Type | Required | Description |
|---|---|---|---|
mfa_token |
string |
yes | |
user_id |
string |
yes | |
method |
string |
yes |
MFAChallengeRequest#
MFA verification request.
| Field | Type | Required | Description |
|---|---|---|---|
mfa_token |
string |
yes | |
user_id |
string | null |
no | |
method |
string |
yes | |
code |
string | null |
no | |
challenge_id |
string | null |
no | |
credential |
object | null |
no | |
remember_me |
boolean |
no | Default: False |
remember_device |
boolean |
no | Default: False |
trust_device |
boolean |
no | Default: False |
device_fingerprint |
string | null |
no |
MFAChallengeResponse#
MFA challenge response.
| Field | Type | Required | Description |
|---|---|---|---|
status |
string |
yes | |
session_id |
string | null |
no | |
redirect_uri |
string | null |
no | |
trusted_device_token |
string | null |
no | |
error |
string | null |
no | |
access_token |
string | null |
no | |
refresh_token |
string | null |
no |
MetaResponse#
Metadata included in API responses.
| Field | Type | Required | Description |
|---|---|---|---|
request_id |
string | null |
no | |
timestamp |
string (date-time) |
no |
RegisterRequest#
Self-registration request.
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
yes | |
password |
string |
yes | |
first_name |
string |
yes | |
last_name |
string |
yes | |
captcha_token |
string | null |
no | |
redirect_uri |
string | null |
no | |
custom_data |
object | null |
no |
RegisterResponse#
Self-registration response.
| Field | Type | Required | Description |
|---|---|---|---|
user_id |
string |
yes | |
status |
string |
yes | |
message |
string |
yes |
ResetPasswordRequest#
Reset password with token.
| Field | Type | Required | Description |
|---|---|---|---|
token |
string |
yes | |
new_password |
string |
yes |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |
scaikey__schemas__auth__LoginRequest#
Direct login request (for hosted login page).
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
yes | |
password |
string |
yes | |
remember_me |
boolean |
no | Default: False |
trusted_device_token |
string | null |
no |
scaikey__schemas__auth__LoginResponse#
Login response.
| Field | Type | Required | Description |
|---|---|---|---|
status |
string |
yes | |
user_id |
string | null |
no | |
mfa_required |
boolean |
no | Default: False |
mfa_token |
string | null |
no | |
available_methods |
array of string | null |
no | |
default_method |
string | null |
no | |
password_change_token |
string | null |
no | |
session_id |
string | null |
no | |
redirect_uri |
string | null |
no |