# Criar chave

Fonte: https://apiwpp.com/docs/api/chaves-de-api/criar-chave
Seção: Chaves de API
Atualizado em: 2026-09-28

`POST /tenants/{id}/api-keys`

Cria uma chave de API para o projeto. A chave é enviada em toda requisição como `Authorization: Bearer <chave>` ou `X-Api-Key: <chave>`. A resposta traz a chave inteira em `key` uma única vez: a apiwpp guarda só o hash SHA-256 dela, então não há como mostrá-la de novo. Guarde-a num cofre de segredos agora. Escopo necessário: `keys:write`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador do projeto (`tenantId`) que recebe a chave. |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `name` | `string` | sim | Para que a chave serve (por exemplo, `CRM produção`). De 1 a 100 caracteres; um nome só com espaços é recusado. (de 1 a 100 caracteres) |
| `scopes` | `string[]` | sim | O que a chave pode fazer: pelo menos um escopo, sem repetição, entre `connections:read`, `connections:write`, `messages:send`, `templates:write`, `webhooks:write`, `logs:read`, `usage:read`, `keys:read` e `keys:write`. Uma chave de API só concede os escopos que ela mesma tem. (mínimo de 1 item; sem itens repetidos) |
| `expiresAt` | `string · date-time \| null` | não | Quando a chave para de funcionar (data e hora ISO 8601, no futuro). `null` ou ausente: nunca expira. Uma chave que expira só cria chaves que expiram até a mesma data. |

## Exemplo de requisição

### cURL

```bash
curl -X POST \
  https://api.apiwpp.com/tenants/$TENANT_ID/api-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM produção",
    "scopes": [
      "connections:read",
      "messages:send"
    ]
  }'
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/tenants/${tenantId}/api-keys`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'CRM produção',
    scopes: [
      'connections:read',
      'messages:send',
    ],
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/tenants/{$tenantId}/api-keys", [
        'name' => 'CRM produção',
        'scopes' => [
            'connections:read',
            'messages:send',
        ],
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/tenants/{tenant_id}/api-keys",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "name": "CRM produção",
        "scopes": [
            "connections:read",
            "messages:send",
        ],
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 201 |  | A chave criada, com a chave inteira em `key`, mostrada só desta vez. Cada chave traz `id`, `tenantId` (o projeto), `organizationId` (a organização do projeto), `name`, `prefix` (identifica a chave; não é secreto), `maskedKey` (`wag_live_<prefixo>_…`, para reconhecer a chave), `scopes`, `status` (`active`, `expired` ou `revoked`), `createdBy` (`apiKey:<id>` da chave que a criou, `user:<id>` do usuário do painel ou `platform`), `createdAt`, `lastUsedAt` (atualizado no máximo uma vez por minuto), `expiresAt`, `revokedAt` e `rotatedAt` (quando uma rotação a substituiu). |
| 400 | `FST_ERR_VALIDATION` | O corpo não segue o schema: sem `name` ou `scopes`, `name` com mais de 100 caracteres, `scopes` vazio, repetido ou com um escopo desconhecido, `expiresAt` fora do formato de data e hora, ou `id` que não é um UUID. `message` diz o que está errado. |
| 400 |  | `name` só tem espaços (`name must not be blank`), ou `expiresAt` não está no futuro (`expiresAt must be in the future`). |
| 401 |  | Sem chave de API, ou com uma chave inválida: desconhecida, revogada, expirada ou de um projeto desativado. O corpo é `{"error": "Unauthorized"}`. |
| 403 |  | A credencial não tem o escopo `keys:write` (`This credential lacks the keys:write scope`); no painel, só donos e administradores criam chaves. |
| 403 |  | A chave que chama pediu escopos que ela não tem (`An API key cannot grant scopes it does not hold: …`, com a lista), ou uma validade maior que a dela: a mensagem diz até quando a nova chave pode valer (`expiresAt must be … or earlier`). |
| 404 |  | O projeto não existe ou não é de quem chama (`Tenant not found`): uma chave de API alcança só o próprio projeto, e o de outra pessoa responde igual a um que não existe. |
| 409 |  | O projeto já tem 50 chaves ativas: revogue uma antes de criar outra. Ou o projeto está desativado; como a chave de um projeto desativado já responde `401`, esse caso só aparece para quem chama pelo painel. |
| 429 |  | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 201 Created

```json
{
  "id": "6f9a2b3c-4d5e-4f6a-9b0c-1d2e3f4a5b6c",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
  "name": "CRM produção",
  "prefix": "q7m4w1zc",
  "maskedKey": "wag_live_q7m4w1zc_…",
  "scopes": [
    "connections:read",
    "messages:send"
  ],
  "status": "active",
  "createdBy": "platform",
  "createdAt": "2026-09-24T12:00:00.000Z",
  "lastUsedAt": null,
  "expiresAt": null,
  "revokedAt": null,
  "rotatedAt": null,
  "key": "wag_live_q7m4w1zc_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8"
}
```

## Detalhes

Uma chave nunca cria outra mais poderosa: uma chave de API só concede escopos que ela mesma tem, e uma chave que expira só cria chaves que expiram até a mesma data (e não chaves sem expiração). Pedir mais do que isso responde `403`.

Um projeto tem no máximo 50 chaves ativas (nem revogadas nem expiradas); a próxima responde `409` até você revogar uma. Um projeto desativado não recebe chaves novas (`409`).

A chave vale só para este projeto e fica com `createdBy` igual a `apiKey:<id>` da chave que a criou (ou `user:<id>` quando criada no painel). Veja [Autenticação](https://apiwpp.com/docs/autenticacao) e [Escopos](https://apiwpp.com/docs/referencia/escopos).

Guia: [Autenticação](https://apiwpp.com/docs/autenticacao).
