Rotacionar chave
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.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador do projeto (tenantId) da chave.
keyIdstring · uuidobrigatórioIdentificador da chave a rotacionar: o id que a listagem e a criação devolvem (não o prefixo).
Corpo da requisição
overlapSecondsintegerPor 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.
Respostas
| Código | Erro e 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_VALIDATIONoverlapSeconds 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.Cabeçalho: Retry-After |
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