---
title: Authentication API
path: reference/api/authentication
status: published
---

# Authentication API

Reference for the `Authentication` endpoint group — 9 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](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/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`](#schema-forgotpasswordrequest)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-scaikey-schemas-auth-loginrequest)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_LoginResponse_`](#schema-apiresponse-loginresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-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`](#schema-mfachallengerequest)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_MFAChallengeResponse_`](#schema-apiresponse-mfachallengeresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-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`](#schema-forgotpasswordrequest)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/auth/tenants/{tenant_slug}/password/reset`

_Reset Password_

Complete password reset with token.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_slug` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`ResetPasswordRequest`](#schema-resetpasswordrequest)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → _any_ |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-registerrequest)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_RegisterResponse_`](#schema-apiresponse-registerresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-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`](#schema-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`](#schema-scaikey-schemas-auth-loginresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_MFAChallengeResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`MFAChallengeResponse`](#schema-mfachallengeresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_RegisterResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`RegisterResponse`](#schema-registerresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ForgotPasswordRequest`

Forgot password request.

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | `string` (`email`) | yes |  |
| `redirect_uri` | `string` \| `null` | no |  |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `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_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 |  |

### `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` (`email`) | 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` (`email`) | 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 |  |
| `session_id` | `string` \| `null` | no |  |
| `redirect_uri` | `string` \| `null` | no |  |