Source: https://ailoot.ai/docs/en/cabinet/keys/ Canonical: https://ailoot.ai/docs/en/cabinet/keys/ Language: en [Dashboard API](https://ailoot.ai/docs/en/) # API keys [Markdown](https://ailoot.ai/docs/en/cabinet/keys/index.md) Methods, request fields, and responses. This section contains 5 methods. Open a method to view access requirements, request fields, and the response. | Method and path | Description | Access | | --- | --- | --- | | `GET /api/v1/keys` | List API keys | Dashboard token | | `POST /api/v1/keys` | Create an API key | Dashboard token | | `DELETE /api/v1/keys/:id` | Delete an API key | Dashboard token | | `GET /api/v1/keys/:id` | Get an API key by ID | Dashboard token | | `PUT /api/v1/keys/:id` | Update an API key | Dashboard token | **GET /api/v1/keys** — List API keys Access: Dashboard token GET`/api/v1/keys` Read operation; use an ID from your previous response ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys" \ -H "Authorization: Bearer $TOKEN" ``` ## Query parameters | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `sort_by` | `string` | no | ; default: created\_at | | `sort_order` | `string` | no | ; default: desc | | `search` | `string` | no | | | `status` | `string` | no | | | `page` | `integer` | no | ; default: 1; positive; page\_size/limit \<=1000 | | `page_size` | `integer` | no | ; default: 20; positive; page\_size/limit \<=1000 | | `limit` | `integer` | no | ; default: 20; positive; page\_size/limit \<=1000 | 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: `APIKey`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "items": [ { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } ], "total": "PLACEHOLDER_TOTAL (integer)", "page": "PLACEHOLDER_PAGE (integer)", "page_size": "PLACEHOLDER_PAGE_SIZE (integer)", "pages": "PLACEHOLDER_PAGES (integer)" } } ``` Note: all personal data and objects are scoped to the JWT subject. Note: the response contains the secret key field. Do not publish real values. **POST /api/v1/keys** — Create an API key Access: Dashboard token POST`/api/v1/keys` ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `name` | `string` | yes | required | | `custom_key` | `string` | no | ; Optional custom key value; may be null | | `ip_whitelist` | `array` | no | ; IP allowlist | | `ip_blacklist` | `array` | no | ; IP blocklist | | `quota` | `number` | no | ; Key spending limit in USD; may be null | | `expires_in_days` | `integer` | no | ; Validity period in days; may be null | | `rate_limit_5h` | `number` | no | ; may be null | | `rate_limit_1d` | `number` | no | ; may be null | | `rate_limit_7d` | `number` | no | ; may be null | Request body template ```json { "name": "PLACEHOLDER_NAME (string)", "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "quota": "PLACEHOLDER_QUOTA (number)", "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)" } ``` 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: `CreateAPIKeyRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `APIKey`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` 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. Note: Idempotency-Key is supported. A repeated request returns the saved response with X-Idempotency-Replayed. Note: the response contains the secret key field. Do not publish real values. 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. **DELETE /api/v1/keys/:id** — Delete an API key Access: Dashboard token DELETE`/api/v1/keys/:id` ## Path parameters | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `id` | `integer` | yes | | No request body is required. ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "message": "VALUE_FROM_RESPONSE" } } ``` 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. Note: the response contains the secret key field. Do not publish real values. 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/keys/:id** — Get an API key by ID Access: Dashboard token GET`/api/v1/keys/:id` Read operation; use an ID from your previous response ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \ -H "Authorization: Bearer $TOKEN" ``` ## Path parameters | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `id` | `integer` | yes | | 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: `APIKey`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` Note: all personal data and objects are scoped to the JWT subject. Note: the response contains the secret key field. Do not publish real values. **PUT /api/v1/keys/:id** — Update an API key Access: Dashboard token PUT`/api/v1/keys/:id` ## Path parameters | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `id` | `integer` | yes | | ## JSON / form fields | The field | Type | Required | Validation / description | | --- | --- | --- | --- | | `name` | `string` | no | | | `status` | `string` | no | omitempty,oneof=active inactive | | `ip_whitelist` | `array` | no | ; Allowed IPs: null leaves the list unchanged; an empty array clears it; may be null | | `ip_blacklist` | `array` | no | ; Blocked IPs: null leaves the list unchanged; an empty array clears it; may be null | | `quota` | `number` | no | ; Key spending limit in USD; 0 means unlimited; may be null | | `expires_at` | `string` | no | ; Expiry time in ISO 8601 format; may be null | | `reset_quota` | `boolean` | no | ; Reset the amount used against the spending limit; may be null | | `rate_limit_5h` | `number` | no | ; may be null | | `rate_limit_1d` | `number` | no | ; may be null | | `rate_limit_7d` | `number` | no | ; may be null | | `reset_rate_limit_usage` | `boolean` | no | ; Reset usage for spending-window limits; may be null | Request body template ```json { "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "quota": "PLACEHOLDER_QUOTA (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)" } ``` 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: `UpdateAPIKeyRequest` ## Response The JSON response contains code, message, and data. The data contents are described in the schemas below. Response data schemas: `APIKey`. See the Data schemas pages for fields and types. Response schema with illustrative values ```json { "code": 0, "message": "success", "data": { "id": "PLACEHOLDER_ID (integer)", "user_id": "PLACEHOLDER_USER_ID (integer)", "key": "PLACEHOLDER_KEY (string)", "name": "PLACEHOLDER_NAME (string)", "status": "PLACEHOLDER_STATUS (string)", "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)", "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)", "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)", "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)", "quota": "PLACEHOLDER_QUOTA (number)", "quota_used": "PLACEHOLDER_QUOTA_USED (number)", "expires_at": "PLACEHOLDER_EXPIRES_AT (string)", "created_at": "PLACEHOLDER_CREATED_AT (string)", "updated_at": "PLACEHOLDER_UPDATED_AT (string)", "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)", "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)", "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)", "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)", "usage_5h": "PLACEHOLDER_USAGE_5H (number)", "usage_1d": "PLACEHOLDER_USAGE_1D (number)", "usage_7d": "PLACEHOLDER_USAGE_7D (number)", "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)", "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)", "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)", "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)", "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)", "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)", "user": "PLACEHOLDER_USER (object)" } } ``` 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. Note: the response contains the secret key field. Do not publish real values. Note: while the key has unfinished requests with reserves, its spending limit cannot be reduced or reset. Send only the fields you want to change. 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. 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.