---
title: "POST | Rotacionar credencial por [id]"
slug: "api-v2-post-rotate-credential"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-post-rotate-credential"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST | Rotacionar credencial por [id]

## 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](/v4-2/docs/how-to-request-a-password-change-from-the-credentials-list).

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](/docs/pt/api-v2-post-rotate-credential#acompanhar-o-job-de-rota%C3%A7%C3%A3o).

              Info

              

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](/v4-2/docs/how-to-manage-authorizations-in-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](/v4-2/docs/how-to-authenticate-an-application-in-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`.

              Info

              

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](/v4-2/docs/api-v2-get-rotation-jobs). |
| →`created_at` | string | Data e hora de criação do job, no formato ISO 8601. Veja os problemas conhecidos em [Jobs de rotação](/v4-2/docs/api-v2-get-rotation-jobs). |
| →`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](/v4-2/docs/api-v2-get-rotation-jobs).

              Info

              

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"
                }
            }
        }
    }
}
```

              Atenção

              

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.

              Info

              

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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).