Pular para o conteúdo

Rotacionar chave

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.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador do projeto (tenantId) da chave.

keyIdstring · uuidobrigatório

Identificador da chave a rotacionar: o id que a listagem e a criação devolvem (não o prefixo).

Corpo da requisição

overlapSecondsinteger

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 0máximo 604800

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
201apiKey (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).
400FST_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.
401Sem chave de API, ou com uma chave inválida: desconhecida, revogada, expirada ou de um projeto desativado. O corpo é {"error": "Unauthorized"}.
403A 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).
404O 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.
409A 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).
409O 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).
429Requisiçõ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

Esta página ajudou? · Atualizado em 28 set 2026