# Revogar chave

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

`DELETE /tenants/{id}/api-keys/{keyId}`

Revoga a chave: ela para de funcionar na hora, e a próxima requisição com ela recebe `401`. A chave continua na listagem, com `status: revoked` e `revokedAt`, para auditoria. Não há como desfazer: para voltar a ter acesso, crie outra chave. 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`. |

## 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 revogar: o `id` que a listagem e a criação devolvem (não o prefixo). |

## Exemplo de requisição

### cURL

```bash
curl -X DELETE \
  https://api.apiwpp.com/tenants/$TENANT_ID/api-keys/$KEY_ID \
  -H "Authorization: Bearer $API_KEY"
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/tenants/${tenantId}/api-keys/${keyId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->delete("https://api.apiwpp.com/tenants/{$tenantId}/api-keys/{$keyId}");
```

### Python

```python
import requests

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

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 200 |  | A chave revogada, com `status: revoked` e `revokedAt` preenchidos. 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` | Um parâmetro de caminho não é um UUID; `message` diz qual. |
| 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 revogar tem escopos que a chave que chama não tem (`An API key cannot revoke a key with scopes it does not hold: …`). |
| 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. |
| 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`. |

### 200 OK

```json
{
  "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": "revoked",
  "createdBy": "platform",
  "createdAt": "2026-09-01T12:00:00.000Z",
  "lastUsedAt": "2026-09-24T12:00:00.000Z",
  "expiresAt": null,
  "revokedAt": "2026-09-24T12:00:00.000Z",
  "rotatedAt": null
}
```

## Detalhes

Revogar uma chave já revogada responde `200` de novo e mantém o `revokedAt` da primeira revogação. Uma chave expirada também pode ser revogada.

Uma chave de API só revoga chaves cujos escopos ela tem, e pode revogar a si mesma: a requisição que a revoga termina normalmente. Para trocar uma chave sem interromper nada, prefira [rotacionar](https://apiwpp.com/docs/api/chaves-de-api/rotacionar-chave).

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