Axuz Developers

POST /api/teams/{teamId}/mail/api-keys/{keyId}/rotate

Rotaciona a chave — segredo NOVO, mesmo id

  • Acesso: Admin da equipe
  • Serviço: https://mail-api.axuz.net

Autenticação aceita

  • sessionCookie — Sessão plena Axuz (cookie de sessão da casa). Sessão restrita é 403 enrollment_required.
  • bearerSession — JWT de acesso da sessão em `Authorization: Bearer`.

F-137. Emite um segredo novo preservando id, nome, scopes, rate limit e allow-list de remetente: o cliente troca só o valor, sem reconfigurar a integração (revogar-e-criar mudaria o id e quebraria painel, métrica de uso e allow-list que apontam pra ele).

grace_seconds ausente ou 0 = a chave antiga deixa de valer no instante da rotação. É o default deliberado — rotação em geral acontece por suspeita do segredo, e nesse caso manter o antigo valendo é o oposto do que se quer. Quem precisa trocar sem downtime pede a janela explicitamente; o teto é 7 dias (604800) e valor acima disso é 400, nunca clamp silencioso.

Dentro da janela, o hash anterior autentica; a expiração é predicado da própria consulta de auth, então fecha sozinha sem depender de job de limpeza.

O plaintext aparece UMA vez, aqui — como no create.

Parâmetros

NomeEmTipoObrigatórioDescrição
teamIdpathstringsim
keyIdpathstringsim

Corpo da requisição

application/json

NomeTipoObrigatórioDescrição
grace_secondsintegernão

Por quantos segundos a chave ANTIGA ainda autentica. 0/ausente = corte imediato.

{
  "grace_seconds": 0
}

Respostas

200

Chave rotacionada (segredo novo, uma única vez)

NomeTipoObrigatórioDescrição
idstring<uuid>não
keystringnão

Plaintext novo — mostrado só nesta resposta

key_prefixstringnão
previous_key_expires_atstring<date-time> | nullnão

Até quando a chave antiga ainda vale; null = já não vale

rotated_atstring<date-time>não

400

keyId malformado, corpo inválido, ou grace_seconds fora de 0..604800

401

Sem credencial valida

NomeTipoObrigatórioDescrição
errorstringsim

403

Não é owner/admin

404

Chave não achada nesse team, ou já revogada

429

Limite de requisições excedido.

NomeTipoObrigatórioDescrição
errorstringsim

500

Erro interno. Tente de novo com backoff; reporte o X-Request-Id.

NomeTipoObrigatórioDescrição
errorstringsim

Exemplos

O "Try it" está desligado nesta referência. Use os exemplos com a sua credencial de teste.

curl

curl -sS -X POST 'https://mail-api.axuz.net/api/teams/TEAM_ID/mail/api-keys/KEY_ID/rotate' \
  -H "Authorization: Bearer $AXUZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grace_seconds":0}'

Node.js

const res = await fetch("https://mail-api.axuz.net/api/teams/TEAM_ID/mail/api-keys/KEY_ID/rotate", {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AXUZ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "grace_seconds": 0
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://mail-api.axuz.net/api/teams/TEAM_ID/mail/api-keys/KEY_ID/rotate",
    headers={
        "Authorization": f"Bearer {os.environ['AXUZ_TOKEN']}",
    },
    json={
        "grace_seconds": 0,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())