Descrição
Solicite a rotação imediata da senha de uma credencial no PAM Core, fora do ciclo de rotação programado da credencial. O caso de uso principal é a resposta a incidentes, quando uma suspeita de comprometimento exige rotacionar a credencial agora, em vez de aguardar o próximo ciclo.
Este endpoint expõe a mesma rotação sob demanda que já está disponível na interface. Para o equivalente na interface, acesse Como solicitar a troca de senha pela lista de credenciais.
A rotação é assíncrona. A troca de senha no dispositivo de destino não é instantânea e pode falhar, por isso a requisição retorna 202 Accepted assim que a rotação é aceita, e a rotação é executada em segundo plano. A resposta traz a referência de um job, que você consulta para saber o que aconteceu. Veja Acompanhar o job de rotação.
Este endpoint informa apenas a rotação que ele iniciou. Ele não retorna o histórico de rotações anteriores de uma credencial. O Segura® expõe esse histórico pela trilha de auditoria por credencial, documentada separadamente.
Pré-requisitos
- Autorização com permissão de leitura e escrita para o PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A.
- Uma política de acesso que conceda à aplicação acesso à credencial que você quer rotacionar.
- Um token de acesso OAuth 2.0 válido com o escopo
credentials:rotate. Para mais informações, acesse Como autenticar uma aplicação A2A. - A credencial deve ter um template de troca configurado. Uma credencial sem template é aceita, mas o job de rotação dela termina em
failed.
Um token de acesso carrega apenas as autorizações que existiam no momento em que foi gerado. Depois que o administrador alterar as permissões da aplicação, gere um novo token, um token existente não passa a ter a nova autorização.
Requisição
POST /api/v2/pam/credentials/{id}/rotate
Parâmetros de caminho
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id |
integer | Sim | Código de identificação único da credencial a rotacionar. |
A requisição não tem corpo.
Exemplo de requisição
POST {{url}}/api/v2/pam/credentials/102/rotate
Resposta
HTTP/1.1 202 Accepted
{
"data": {
"job": {
"id": "48",
"type": "rotate",
"state": "queued",
"created_at": "2026-08-20T16:57:13-03:00",
"related_resource": {
"type": "credential",
"id": "102"
}
}
}
}
Um 202 Accepted significa que a rotação foi aceita e enfileirada, não que a senha foi alterada. Consulte o job para saber se ela foi concluída.
Campos do corpo da resposta
| Campo | Tipo | Descrição |
|---|---|---|
data |
object | Envelope da resposta. |
data.job |
object | O job de rotação criado por esta requisição. Veja a tabela a seguir. |
job
| Campo | Tipo | Descrição |
|---|---|---|
→id |
string | Código de identificação único do job. Use-o para consultar, cancelar ou reexecutar a rotação. |
→type |
string | Tipo do job. Sempre rotate para este endpoint. |
→state |
string | Estado atual do job. Valores permitidos: queued, running, succeeded, failed, canceled. Acesse Jobs de rotação. |
→created_at |
string | Data e hora de criação do job, no formato ISO 8601. Veja os problemas conhecidos em Jobs de rotação. |
→related_resource |
object | O recurso sobre o qual o job atua. |
→→type |
string | Tipo do recurso. credential para rotações iniciadas por este endpoint. |
→→id |
string | Código de identificação único da credencial que está sendo rotacionada. |
Acompanhar o job de rotação
Consulte o job para saber se a rotação foi concluída:
GET /api/v2/pam/jobs/{job-id}
Um job de rotação passa por cinco estados — queued, running, succeeded, failed e canceled. Enquanto o job está em queued, você pode cancelá-lo; depois que ele termina em failed, você pode solicitar uma nova tentativa. Um job que falha traz o motivo em um objeto error.
Para o contrato completo do job, a tabela de estados e as ações de cancelamento e reexecução, acesse Jobs de rotação.
Um 202 Accepted significa que a rotação foi aceita e enfileirada, não que a senha foi alterada. Confirme sempre o resultado consultando o job.
Erros
| Código HTTP | Mensagem | Causa possível | Solução |
|---|---|---|---|
401 |
api.auth.token.invalid |
O token de acesso está ausente ou expirou. | Solicite um novo token de acesso. |
403 |
api.auth.forbidden |
A aplicação não está autorizada para esta credencial. | Peça ao administrador para verificar a permissão de PAM Core da aplicação e a política de acesso que cobre esta credencial, e gere um novo token. |
404 |
api.resource.not_found |
A credencial não existe ou está fora do escopo da autorização. | Verifique o código de identificação enviado no caminho. |
409 |
api.resource.conflict.rotation_pending |
Já existe uma rotação em andamento para esta credencial. | Acompanhe o job indicado em details.job em vez de reenviar a requisição. |
429 |
rate_limit_exceeded |
O limite de requisições foi excedido. | Reduza a frequência de requisições e tente novamente. |
500 |
api.internal.error |
Erro interno do servidor. | Entre em contato com a equipe de suporte da Segura®. |
Exemplo de resposta de erro
409 já existe uma rotação em andamento:
{
"error": {
"code": "api.resource.conflict.rotation_pending",
"message": "A rotation is already in progress for this credential.",
"details": {
"job": {
"id": "48",
"type": "rotate",
"links": {
"self": "/api/v2/pam/jobs/48"
}
}
}
}
}
Um 409 é comportamento esperado, não um defeito. O Segura® recusa uma segunda rotação em uma credencial que já está rotacionando, porque duas rotações disputando a mesma senha do dispositivo podem deixar o cofre e o dispositivo dessincronizados.
O 409 também ocorre quando o próprio Segura® iniciou a rotação, por exemplo ao encerrar uma sessão privilegiada ou ao devolver a custódia de uma credencial. Uma automação pode, portanto, receber 409 sem ter solicitado nada. Leia details.job para identificar a rotação já em andamento e acompanhe esse job, em vez de tentar novamente.
O bloqueio de rotação vale por credencial, não globalmente. Um 409 em uma credencial não impede que você rotacione outra.
Para mensagens de erros de autenticação e as regras compartilhadas de 403 e 404, acesse API v2 - Convenções e comportamentos compartilhados.