Source: https://ailoot.ai/docs/pt-pt/cabinet/keys/ Canonical: https://ailoot.ai/docs/pt-pt/cabinet/keys/ Language: pt-pt [API da área pessoal](https://ailoot.ai/docs/pt-pt/) # Chaves de API [Markdown](https://ailoot.ai/docs/pt-pt/cabinet/keys/index.md) Métodos, campos dos pedidos e respostas. Esta secção contém 5 métodos. Abra o método para consultar as condições de acesso, os campos do pedido e a resposta. | Método e caminho | Descrição | Acesso | | --- | --- | --- | | `GET /api/v1/keys` | Lista — chaves de API | Token da área pessoal | | `POST /api/v1/keys` | Criação de uma chave de API | Token da área pessoal | | `DELETE /api/v1/keys/:id` | Eliminação — chaves de API | Token da área pessoal | | `GET /api/v1/keys/:id` | Obtenção por identificador — chaves de API | Token da área pessoal | | `PUT /api/v1/keys/:id` | Alteração de uma chave de API | Token da área pessoal | **GET /api/v1/keys** — Lista — chaves de API Acesso: token da área pessoal GET`/api/v1/keys` Leitura; o ID é obtido da sua resposta anterior ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys" \ -H "Authorization: Bearer $TOKEN" ``` ## Parâmetros de consulta | O campo | Tipo | Obrigatório | Validação / descrição | | --- | --- | --- | --- | | `sort_by` | `string` | não | ; por predefinição: created\_at | | `sort_order` | `string` | não | ; por predefinição: desc | | `search` | `string` | não | | | `status` | `string` | não | | | `page` | `integer` | não | ; por predefinição: 1; positive; page\_size/limit \<=1000 | | `page_size` | `integer` | não | ; por predefinição: 20; positive; page\_size/limit \<=1000 | | `limit` | `integer` | não | ; por predefinição: 20; positive; page\_size/limit \<=1000 | Não é necessário corpo do pedido. Transmita os parâmetros indicados acima no URL. ## Resposta A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo. Esquemas de dados da resposta: `APIKey`. Os campos e os tipos estão nas páginas «Esquemas de dados». Esquema da resposta, com valores ilustrativos ```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)" } } ``` Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT. Particularidades: a resposta contém o valor secreto key; não publique valores reais. **POST /api/v1/keys** — Criação de uma chave de API Acesso: token da área pessoal POST`/api/v1/keys` ## Campos JSON / formulário | O campo | Tipo | Obrigatório | Validação / descrição | | --- | --- | --- | --- | | `name` | `string` | sim | required | | `custom_key` | `string` | não | ; Valor personalizado opcional da chave; pode ser null | | `ip_whitelist` | `array` | não | ; Lista de IP permitidos | | `ip_blacklist` | `array` | não | ; Lista de IP bloqueados | | `quota` | `number` | não | ; Limite de despesas da chave em USD; pode ser null | | `expires_in_days` | `integer` | não | ; Prazo de validade em dias; pode ser null | | `rate_limit_5h` | `number` | não | ; pode ser null | | `rate_limit_1d` | `number` | não | ; pode ser null | | `rate_limit_7d` | `number` | não | ; pode ser null | Modelo do corpo do pedido ```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 representa os seus dados de entrada e o respetivo tipo. Substitua os valores e mantenha apenas os campos opcionais necessários; não envie marcadores de texto no lugar de números, booleanos, objetos ou arrays. Esquema do pedido: `CreateAPIKeyRequest` ## Resposta A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo. Esquemas de dados da resposta: `APIKey`. Os campos e os tipos estão nas páginas «Esquemas de dados». Esquema da resposta, com valores ilustrativos ```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)" } } ``` Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT. Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado. Particularidades: Idempotency-Key é suportado; a repetição devolve a resposta guardada com X-Idempotency-Replayed. Particularidades: a resposta contém o valor secreto key; não publique valores reais. O método altera dados. Reenviar só é seguro quando o método indica Idempotency-Key. Se a resposta se perder, verifique primeiro o resultado (por exemplo, a lista de chaves) e só depois decida se deve repetir o pedido. **DELETE /api/v1/keys/:id** — Eliminação — chaves de API Acesso: token da área pessoal DELETE`/api/v1/keys/:id` ## Parâmetros do caminho | O campo | Tipo | Obrigatório | Validação / descrição | | --- | --- | --- | --- | | `id` | `integer` | sim | | Não é necessário corpo do pedido. ## Resposta A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo. Esquema da resposta, com valores ilustrativos ```json { "code": 0, "message": "success", "data": { "message": "VALUE_FROM_RESPONSE" } } ``` Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT. Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado. Particularidades: a resposta contém o valor secreto key; não publique valores reais. O método altera dados. Reenviar só é seguro quando o método indica Idempotency-Key. Se a resposta se perder, verifique primeiro o resultado (por exemplo, a lista de chaves) e só depois decida se deve repetir o pedido. **GET /api/v1/keys/:id** — Obtenção por identificador — chaves de API Acesso: token da área pessoal GET`/api/v1/keys/:id` Leitura; o ID é obtido da sua resposta anterior ```bash curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \ -H "Authorization: Bearer $TOKEN" ``` ## Parâmetros do caminho | O campo | Tipo | Obrigatório | Validação / descrição | | --- | --- | --- | --- | | `id` | `integer` | sim | | Não é necessário corpo do pedido. Transmita os parâmetros indicados acima no URL. ## Resposta A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo. Esquemas de dados da resposta: `APIKey`. Os campos e os tipos estão nas páginas «Esquemas de dados». Esquema da resposta, com valores ilustrativos ```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)" } } ``` Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT. Particularidades: a resposta contém o valor secreto key; não publique valores reais. **PUT /api/v1/keys/:id** — Alteração de uma chave de API Acesso: token da área pessoal PUT`/api/v1/keys/:id` ## Parâmetros do caminho | O campo | Tipo | Obrigatório | Validação / descrição | | --- | --- | --- | --- | | `id` | `integer` | sim | | ## Campos JSON / formulário | O campo | Tipo | Obrigatório | Validação / descrição | | --- | --- | --- | --- | | `name` | `string` | não | | | `status` | `string` | não | omitempty,oneof=active inactive | | `ip_whitelist` | `array` | não | ; IP permitidos: null não altera a lista, um array vazio limpa-a; pode ser null | | `ip_blacklist` | `array` | não | ; IP bloqueados: null não altera a lista, um array vazio limpa-a; pode ser null | | `quota` | `number` | não | ; Limite de despesas da chave em USD; 0 — sem limite; pode ser null | | `expires_at` | `string` | não | ; Data e hora de expiração no formato ISO 8601; pode ser null | | `reset_quota` | `boolean` | não | ; Repor a parte utilizada do limite de despesas; pode ser null | | `rate_limit_5h` | `number` | não | ; pode ser null | | `rate_limit_1d` | `number` | não | ; pode ser null | | `rate_limit_7d` | `number` | não | ; pode ser null | | `reset_rate_limit_usage` | `boolean` | não | ; Repor o consumo dos limites por janela; pode ser null | Modelo do corpo do pedido ```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 representa os seus dados de entrada e o respetivo tipo. Substitua os valores e mantenha apenas os campos opcionais necessários; não envie marcadores de texto no lugar de números, booleanos, objetos ou arrays. Esquema do pedido: `UpdateAPIKeyRequest` ## Resposta A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo. Esquemas de dados da resposta: `APIKey`. Os campos e os tipos estão nas páginas «Esquemas de dados». Esquema da resposta, com valores ilustrativos ```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)" } } ``` Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT. Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado. Particularidades: a resposta contém o valor secreto key; não publique valores reais. Particularidades: enquanto existirem pedidos por concluir com reserva associados à chave, o respetivo limite de despesas não pode ser reduzido nem reposto. Envie apenas os campos que pretende alterar. O método altera dados. Reenviar só é seguro quando o método indica Idempotency-Key. Se a resposta se perder, verifique primeiro o resultado (por exemplo, a lista de chaves) e só depois decida se deve repetir o pedido. Ainda tem dúvidas? Envie o Request ID e uma descrição — ajudamos a esclarecer.[Contactar o suporte](mailto:support@ailoot.ai) ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.