# Rotacionar chave

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

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

Rotaciona a chave: cria uma chave nova com o mesmo nome, os mesmos escopos e a mesma validade da antiga, mostrada uma única vez em `apiKey.key`. A antiga continua funcionando por `overlapSeconds` (padrão: 24 horas), para o seu sistema trocar de chave sem interrupção; `0` revoga a antiga na hora. 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` | não | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador do projeto (`tenantId`) da chave. |
| `keyId` | `string · uuid` | sim | Identificador da chave a rotacionar: o `id` que a listagem e a criação devolvem (não o prefixo). |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `overlapSeconds` | `integer` | não | Por quantos segundos a chave antiga continua funcionando depois da rotação. Padrão: 86400 (24 horas); máximo: 604800 (7 dias). `0` revoga a antiga na hora. (mínimo 0; máximo 604800) |

## Exemplo de requisição

### cURL

```bash
curl -X POST \
  https://api.apiwpp.com/tenants/$TENANT_ID/api-keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "overlapSeconds": 3600
  }'
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/tenants/${tenantId}/api-keys/${keyId}/rotate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    overlapSeconds: 3600,
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/tenants/{$tenantId}/api-keys/{$keyId}/rotate", [
        'overlapSeconds' => 3600,
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/tenants/{tenant_id}/api-keys/{key_id}/rotate",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "overlapSeconds": 3600,
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 201 |  | `apiKey` (a chave nova, com a chave inteira em `key`, mostrada só desta vez) e `previous` (a antiga, com `rotatedAt` e o `expiresAt` do fim da sobreposição). 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` | `overlapSeconds` não é um número inteiro entre 0 e 604800, ou um parâmetro de caminho não é um UUID. `message` diz o que está errado. |
| 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`), ou a chave a rotacionar tem escopos que a chave que chama não tem (`An API key cannot rotate a key with scopes it does not hold: …`), ou dura mais que ela (`An API key cannot rotate a key that outlives it`). |
| 404 |  | O projeto não é de quem chama (`Tenant not found`), ou a chave não existe nesse projeto (`API key not found`). A chave de outro projeto responde igual a uma que não existe. |
| 409 |  | A chave já foi rotacionada (`This API key has already been rotated`), foi revogada (`This API key is revoked`) ou expirou (`This API key has expired`). |
| 409 |  | O projeto já tem 50 chaves ativas além da que está sendo rotacionada, ou está desativado (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
{
  "apiKey": {
    "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"
  },
  "previous": {
    "id": "5e8f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
    "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
    "organizationId": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d",
    "name": "CRM produção",
    "prefix": "k3x9p2ab",
    "maskedKey": "wag_live_k3x9p2ab_…",
    "scopes": [
      "connections:read",
      "messages:send"
    ],
    "status": "active",
    "createdBy": "platform",
    "createdAt": "2026-09-01T12:00:00.000Z",
    "lastUsedAt": "2026-09-24T12:00:00.000Z",
    "expiresAt": "2026-09-24T13:00:00.000Z",
    "revokedAt": null,
    "rotatedAt": "2026-09-24T12:00:00.000Z"
  }
}
```

## Detalhes

A antiga recebe `rotatedAt` e um `expiresAt` no fim da sobreposição; se ela já expirava antes disso, a data dela vale. Durante a sobreposição ela continua `active`; depois, passa a `expired`. Com `overlapSeconds: 0`, ela fica `revoked` na hora.

Uma chave é rotacionada uma vez só: rotacioná-la de novo, ou rotacionar uma chave revogada ou expirada, responde `409`. Para rotacionar outra vez, rotacione a chave nova.

O corpo é opcional: sem corpo (e sem o cabeçalho `Content-Type`), vale a sobreposição padrão de 24 horas. A chave antiga não conta no limite de 50 chaves ativas do projeto.

Uma chave de API só rotaciona chaves cujos escopos ela tem, e, se ela expira, só chaves que expiram até a mesma data. Ela pode rotacionar a si mesma e continuar chamando com a antiga até o fim da sobreposição.

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