Portal Auth API
Reference for the Portal Auth endpoint group — 6 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/authenticate#
Authenticate User
Step 2 of login: Verify password and issue tokens.
Requires a valid flow_token from the identify step. If user belongs to multiple tenants, tenant_id must be specified.
Request body:
Required.
application/json→AuthenticateRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → AuthenticateResponse |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/identify#
Identify User
Step 1 of login: Identify user and return available tenants.
This endpoint is designed to be safe against enumeration attacks:
- Always returns a flow token (even for non-existent users)
- Response format is identical for existing and non-existing users
- Uses constant-time operations where possible
Request body:
Required.
application/json→IdentifyRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → IdentifyResponse |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/login#
Portal Login
Simple one-step login (backwards compatible).
If user exists in multiple tenants and tenant_id is not provided, returns an error asking for tenant selection.
Request body:
Required.
application/json→scaikey__api__v1__me__auth__LoginRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → scaikey__api__v1__me__auth__LoginResponse |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/logout#
Portal Logout
Logout from the user portal.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → object |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/mfa/verify#
Portal Mfa Verify
Verify MFA code for the portal two-step login flow.
After /authenticate returns MFA_REQUIRED, the frontend calls this endpoint with the mfa_token and the TOTP/email/backup code.
Request body:
Required.
application/json→PortalMFAVerifyRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → PortalMFAVerifyResponse |
422 |
application/json → HTTPValidationError |
POST /api/v1/auth/refresh#
Portal Refresh
Refresh access token.
Request body:
Required.
application/json→scaikey__api__v1__me__auth__RefreshRequest
Responses:
| Status | Body |
|---|---|
200 |
application/json → scaikey__api__v1__me__auth__RefreshResponse |
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.
AuthenticateRequest#
| Field | Type | Required | Description |
|---|---|---|---|
flow_token |
string |
yes | |
tenant_id |
string | null |
no | |
password |
string |
yes |
AuthenticateResponse#
| Field | Type | Required | Description |
|---|---|---|---|
status |
string |
no | Default: SUCCESS |
access_token |
string | null |
no | |
refresh_token |
string | null |
no | |
user |
object | null |
no | |
mfa_token |
string | null |
no | |
user_id |
string | null |
no | |
available_methods |
array of string | null |
no |
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
IdentifyRequest#
| Field | Type | Required | Description |
|---|---|---|---|
email |
string (email) |
yes |
IdentifyResponse#
| Field | Type | Required | Description |
|---|---|---|---|
flow_token |
string |
yes | |
tenants |
array of object | yes | |
requires_tenant_selection |
boolean |
yes |
PortalMFAVerifyRequest#
| Field | Type | Required | Description |
|---|---|---|---|
mfa_token |
string |
yes | |
user_id |
string |
yes | |
method |
string |
yes | |
code |
string | null |
no | |
trust_device |
boolean |
no | Default: False |
PortalMFAVerifyResponse#
| Field | Type | Required | Description |
|---|---|---|---|
access_token |
string |
yes | |
refresh_token |
string |
yes | |
user |
object | yes |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |
scaikey__api__v1__me__auth__LoginRequest#
| Field | Type | Required | Description |
|---|---|---|---|
email |
string (email) |
yes | |
password |
string |
yes | |
tenant_id |
string | null |
no |
scaikey__api__v1__me__auth__LoginResponse#
| Field | Type | Required | Description |
|---|---|---|---|
access_token |
string |
yes | |
refresh_token |
string |
yes | |
user |
object | yes |
scaikey__api__v1__me__auth__RefreshRequest#
| Field | Type | Required | Description |
|---|---|---|---|
refresh_token |
string |
yes |
scaikey__api__v1__me__auth__RefreshResponse#
| Field | Type | Required | Description |
|---|---|---|---|
access_token |
string |
yes | |
refresh_token |
string | null |
no |