Source: https://ailoot.ai/docs/cabinet/auth/ Canonical: https://ailoot.ai/docs/en/cabinet/auth/ Language: en [Dashboard API](https://ailoot.ai/docs/en/) # Sign-in and sessions [Markdown](https://ailoot.ai/docs/en/cabinet/auth/index.md) Methods, request fields, and responses. This section contains 14 methods. Open a method to view access requirements, request fields, and the response. | Method and path | Description | Access | | --- | --- | --- | | `POST /api/v1/auth/forgot-password` | Request a password reset | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/login` | Sign in with email and password | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/login/2fa` | Complete sign-in with TOTP | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/logout` | Sign out and revoke a refresh token | No sign-in required; additional requirements are listed for the method | | `GET /api/v1/auth/me` | Current user, balance, and limits | Dashboard token | | `POST /api/v1/auth/passkey/login/begin` | Begin passkey sign-in | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/passkey/login/finish` | Complete passkey sign-in | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/refresh` | Refresh tokens | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/register` | Sign up | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/reset-password` | Reset password | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/revoke-all-sessions` | Revoke all sessions | Dashboard token | | `POST /api/v1/auth/send-verify-code` | Send a verification code | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/validate-invitation-code` | Validate an invitation | No sign-in required; additional requirements are listed for the method | | `POST /api/v1/auth/validate-promo-code` | Validate a promo code | No sign-in required; additional requirements are listed for the method | **POST /api/v1/auth/forgot-password** — Request a password reset Access: no sign-in required; additional requirements are listed for the method Rate limit: 5 requests per 60 seconds per address. POST`/api/v1/auth/forgot-password` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `email` | `string` | yes | required,email | | `turnstile_token` | `string` | no | | Request body template ```json { "email": "PLACEHOLDER_EMAIL (string)", "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `ForgotPasswordRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `ForgotPasswordResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "message": "PLACEHOLDER_MESSAGE (string)" } } ``` Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/login** — Sign in with email and password Access: no sign-in required; additional requirements are listed for the method Feature availability and additional access requirements are checked when the request is processed. Rate limit: 20 requests per 60 seconds per address. POST`/api/v1/auth/login` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `email` | `string` | yes | required,email | | `password` | `string` | yes | required | | `turnstile_token` | `string` | no | | Request body template ```json { "email": "PLACEHOLDER_EMAIL (string)", "password": "PLACEHOLDER_PASSWORD (string)", "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `LoginRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `TotpLoginResponse`, `User`, `AuthResponse`. See the Data schemas pages for fields and types. Where several response variants are possible, their fields are listed in separate schemas; do not combine them into one object. Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/login/2fa** — Complete sign-in with TOTP Access: no sign-in required; additional requirements are listed for the method Feature availability and additional access requirements are checked when the request is processed. Rate limit: 20 requests per 60 seconds per address. POST`/api/v1/auth/login/2fa` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `temp_token` | `string` | yes | required | | `totp_code` | `string` | yes | required,len=6 | Request body template ```json { "temp_token": "PLACEHOLDER_TEMP_TOKEN (string)", "totp_code": "PLACEHOLDER_TOTP_CODE (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `Login2FARequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `User`, `AuthResponse`. See the Data schemas pages for fields and types. Where several response variants are possible, their fields are listed in separate schemas; do not combine them into one object. Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/logout** — Sign out and revoke a refresh token Access: no sign-in required; additional requirements are listed for the method POST`/api/v1/auth/logout` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `refresh_token` | `string` | no | ; Optional: revoke the specified refresh token | Request body template ```json { "refresh_token": "PLACEHOLDER_REFRESH_TOKEN (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `LogoutRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `LogoutResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "message": "PLACEHOLDER_MESSAGE (string)" } } ``` Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **GET /api/v1/auth/me** — Current user, balance, and limits Access: Dashboard token GET`/api/v1/auth/me` Read operation; use an ID from your previous response ```bash curl --fail-with-body "https://ailoot.ai/api/v1/auth/me" \ -H "Authorization: Bearer $TOKEN" ``` No request body is required. Send the parameters listed above in the URL. ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `User`, `UserProfileResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "email": "PLACEHOLDER_EMAIL (string)", "username": "PLACEHOLDER_USERNAME (string)", "role": "PLACEHOLDER_ROLE (string)", "balance": "PLACEHOLDER_BALANCE (number)", "frozen_balance": "PLACEHOLDER_FROZEN_BALANCE (number)", "concurrency": "PLACEHOLDER_CONCURRENCY (integer)", "status": "PLACEHOLDER_STATUS (string)", "last_active_at": "PLACEHOLDER_LAST_ACTIVE_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "deleted_at": "PLACEHOLDER_DELETED_AT (string)", "balance_notify_enabled": "PLACEHOLDER_BALANCE_NOTIFY_ENABLED (boolean)", "balance_notify_threshold_type": "PLACEHOLDER_BALANCE_NOTIFY_THRESHOLD_TYPE (string)", "balance_notify_threshold": "PLACEHOLDER_BALANCE_NOTIFY_THRESHOLD (number)", "balance_notify_extra_emails": "PLACEHOLDER_BALANCE_NOTIFY_EXTRA_EMAILS (array)", "total_recharged": "PLACEHOLDER_TOTAL_RECHARGED (number)", "rpm_limit": "PLACEHOLDER_RPM_LIMIT (integer)", "api_keys": "PLACEHOLDER_API_KEYS (array)", "avatar_url": "PLACEHOLDER_AVATAR_URL (string)", "email_bound": "PLACEHOLDER_EMAIL_BOUND (boolean)" } } ``` Note: all personal data and objects are scoped to the JWT subject. Note: key spending limits (quota, quota\_used) are returned in key responses, not in the profile. frozen\_balance is the reserved amount; do not treat it as available balance. **POST /api/v1/auth/passkey/login/begin** — Begin passkey sign-in Access: no sign-in required; additional requirements are listed for the method Feature availability and additional access requirements are checked when the request is processed. Rate limit: 20 requests per 60 seconds per address. POST`/api/v1/auth/passkey/login/begin` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `turnstile_token` | `string` | no | | Request body template ```json { "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `PasskeyBeginLoginRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `PasskeyOptionsResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "session_token": "PLACEHOLDER_SESSION_TOKEN (string)", "options": "PLACEHOLDER_OPTIONS (any)" } } ``` Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. Note: credential comes from navigator.credentials; session\_token comes from begin. The finish body must be \<=65536 bytes. Registration and deletion require a password. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/passkey/login/finish** — Complete passkey sign-in Access: no sign-in required; additional requirements are listed for the method Feature availability and additional access requirements are checked when the request is processed. Rate limit: 20 requests per 60 seconds per address. POST`/api/v1/auth/passkey/login/finish` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `session_token` | `string` | yes | required | | `name` | `string` | no | | | `credential` | `object` | yes | required | Request body template ```json { "session_token": "PLACEHOLDER_SESSION_TOKEN (string)", "name": "PLACEHOLDER_NAME (string)", "credential": "PLACEHOLDER_CREDENTIAL (object)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `PasskeyFinishRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `User`, `AuthResponse`. See the Data schemas pages for fields and types. Where several response variants are possible, their fields are listed in separate schemas; do not combine them into one object. Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. Note: credential comes from navigator.credentials; session\_token comes from begin. The finish body must be \<=65536 bytes. Registration and deletion require a password. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/refresh** — Refresh tokens Access: no sign-in required; additional requirements are listed for the method Feature availability and additional access requirements are checked when the request is processed. Rate limit: 30 requests per 60 seconds per address. POST`/api/v1/auth/refresh` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `refresh_token` | `string` | yes | required | Request body template ```json { "refresh_token": "PLACEHOLDER_REFRESH_TOKEN (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `RefreshTokenRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `RefreshTokenResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "access_token": "PLACEHOLDER_ACCESS_TOKEN (string)", "refresh_token": "PLACEHOLDER_REFRESH_TOKEN (string)", "expires_in": "PLACEHOLDER_EXPIRES_IN (integer)", "token_type": "PLACEHOLDER_TOKEN_TYPE (string)" } } ``` Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/register** — Sign up Access: no sign-in required; additional requirements are listed for the method Rate limit: 5 requests per 60 seconds per address. POST`/api/v1/auth/register` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `email` | `string` | yes | required,email | | `password` | `string` | yes | required,min=6 | | `verify_code` | `string` | no | | | `turnstile_token` | `string` | no | | | `promo_code` | `string` | no | ; Registration promo code | | `invitation_code` | `string` | no | ; Invitation code | Request body template ```json { "email": "PLACEHOLDER_EMAIL (string)", "password": "PLACEHOLDER_PASSWORD (string)", "verify_code": "PLACEHOLDER_VERIFY_CODE (string)", "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)", "promo_code": "PLACEHOLDER_PROMO_CODE (string)", "invitation_code": "PLACEHOLDER_INVITATION_CODE (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `RegisterRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `User`, `AuthResponse`. See the Data schemas pages for fields and types. Where several response variants are possible, their fields are listed in separate schemas; do not combine them into one object. Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/reset-password** — Reset password Access: no sign-in required; additional requirements are listed for the method Rate limit: 10 requests per 60 seconds per address. POST`/api/v1/auth/reset-password` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `email` | `string` | yes | required,email | | `token` | `string` | yes | required | | `new_password` | `string` | yes | required,min=6 | Request body template ```json { "email": "PLACEHOLDER_EMAIL (string)", "token": "PLACEHOLDER_TOKEN (string)", "new_password": "PLACEHOLDER_NEW_PASSWORD (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `ResetPasswordRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `ResetPasswordResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "message": "PLACEHOLDER_MESSAGE (string)" } } ``` Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/revoke-all-sessions** — Revoke all sessions Access: Dashboard token POST`/api/v1/auth/revoke-all-sessions` No request body is required. ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `RevokeAllSessionsResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "message": "PLACEHOLDER_MESSAGE (string)" } } ``` Note: all personal data and objects are scoped to the JWT subject. Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/send-verify-code** — Send a verification code Access: no sign-in required; additional requirements are listed for the method Rate limit: 5 requests per 60 seconds per address. POST`/api/v1/auth/send-verify-code` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `email` | `string` | yes | required,email | | `turnstile_token` | `string` | no | | Request body template ```json { "email": "PLACEHOLDER_EMAIL (string)", "turnstile_token": "PLACEHOLDER_TURNSTILE_TOKEN (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `SendVerifyCodeRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `SendVerifyCodeResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "message": "PLACEHOLDER_MESSAGE (string)", "countdown": "PLACEHOLDER_COUNTDOWN (integer)" } } ``` Note: this operation changes state or continues a one-time authentication flow. The example describes the contract and is not executed. This method changes data. Resending is safe only where the method specifies Idempotency-Key. If the response is lost, first check the result—for example, the key list—before deciding whether to resend the request. **POST /api/v1/auth/validate-invitation-code** — Validate an invitation Access: no sign-in required; additional requirements are listed for the method Feature availability and additional access requirements are checked when the request is processed. Rate limit: 10 requests per 60 seconds per address. POST`/api/v1/auth/validate-invitation-code` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `code` | `string` | yes | required | Request body template ```json { "code": "PLACEHOLDER_CODE (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `ValidateInvitationCodeRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `ValidateInvitationCodeResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "valid": "PLACEHOLDER_VALID (boolean)", "error_code": "PLACEHOLDER_ERROR_CODE (string)" } } ``` Notes: This method checks the invitation without redeeming the code; the example describes the contract and is not executed. This method only checks the invitation code and does not consume it. You can repeat the check within the rate limit; the result reflects the state of the code at the time of the request. **POST /api/v1/auth/validate-promo-code** — Validate a promo code Access: no sign-in required; additional requirements are listed for the method Feature availability and additional access requirements are checked when the request is processed. Rate limit: 10 requests per 60 seconds per address. POST`/api/v1/auth/validate-promo-code` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `code` | `string` | yes | required | Request body template ```json { "code": "PLACEHOLDER_CODE (string)" } ``` PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays. Request schema: `ValidatePromoCodeRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `ValidatePromoCodeResponse`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "valid": "PLACEHOLDER_VALID (boolean)", "bonus_amount": "PLACEHOLDER_BONUS_AMOUNT (number)", "error_code": "PLACEHOLDER_ERROR_CODE (string)", "message": "PLACEHOLDER_MESSAGE (string)" } } ``` Notes: This method checks the promo code without awarding a bonus; the example describes the contract and is not executed. This method only checks the promo code and does not apply it to the account. You can repeat the check within the rate limit; the result reflects the state of the code at the time of the request. ## Sign-in and sessions · 2FA `POST /api/v1/auth/login` → `data` - `data.requires_2fa === true` → [TotpLoginResponse](https://ailoot.ai/docs/en/cabinet/schemas-1/#totploginresponse) → `data.temp_token` → `POST /api/v1/auth/login/2fa` · `{"temp_token": "…", "totp_code": "…"}` → `data.access_token` - `data.access_token` → [AuthResponse](https://ailoot.ai/docs/en/cabinet/schemas-1/#authresponse) → `Authorization: Bearer $TOKEN` `totp_code`: `string`, `len = 6`. `temp_token ≠ access_token`. [User](https://ailoot.ai/docs/en/cabinet/schemas-1/#user) Still have questions? Send your Request ID and a description — we'll help you troubleshoot.[Contact support](mailto:support@ailoot.ai) ## Ailoot · The company and its project portfolio Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control. The company and its project portfolio: millions of customers; monthly sales in the billions. Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.