--- title: "POST | Rotacionar chave SSH" slug: "api-v2-post-rotate-ssh-key" updated: 2026-11-03T14:47:51Z published: 2026-11-03T14:47:51Z canonical: "docs.senhasegura.io/api-v2-post-rotate-ssh-key" --- > ## 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 chave SSH ## Descrição Renove um par de chaves SSH no PAM Core. A plataforma gera um novo par e substitui a chave existente no dispositivo principal associado ao registro. A rotação é assíncrona, porque conecta ao dispositivo principal para executar a troca. O endpoint retorna `202 Accepted` com um job, e não o resultado final. A rotação segue as configurações de `key_renewal` da chave SSH, que você pode consultar com [GET | Listar uma chave SSH por [id]](/v4-2/docs/api-v2-get-list-an-ssh-key). Alert A rotação substitui o material da chave no dispositivo de destino. Qualquer sistema que ainda utilize a chave privada anterior perde o acesso assim que a troca é concluída. Confirme quais consumidores dependem da chave antes de rotacioná-la. --- ## Pré-requisitos - Autorização com permissão de **leitura e escrita** no PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a). - Um token de acesso OAuth 2.0 válido. Para mais informações, acesse [Como autenticar uma aplicação A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a). - A chave SSH deve estar ativa. Rotacionar uma chave inativa retorna `409`. - A chave SSH deve ter um dispositivo principal, e a plataforma precisa conseguir alcançá-lo. --- ## Requisição `POST` `/api/v2/pam/ssh-keys/{id}/rotate` ### Parâmetros de caminho | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `id` | string | Sim | Código único de identificação da chave SSH, atribuído pela Segura™. | A requisição não tem corpo. --- ### Exemplo de requisição `POST` `{{url}}/api/v2/pam/ssh-keys/2267/rotate` --- ## Resposta ``` HTTP/1.1 202 Accepted ``` ### Exemplo de corpo da resposta ``` { "data": { "job": { "id": "3635", "type": "rotate", "state": "queued" } }, "meta": { "links": { "self": "/api/v2/pam/jobs/3635" } } } ``` --- ## Campos do corpo da resposta | Campo | Tipo | Descrição | | --- | --- | --- | | `data.job` | object | O job assíncrono criado para esta rotação. | | `data.job.id` | string | Código único de identificação do job. | | `data.job.type` | string | Tipo do job. Sempre `rotate` neste endpoint. | | `data.job.state` | string | Estado atual do job. Um job recém-criado fica em `queued`. | | `meta.links.self` | string | URL do recurso de job, usada para acompanhar a rotação. | ### Acompanhar o job Envie uma requisição `GET` para a URL indicada em `meta.links.self` para ler o estado atual da rotação: `GET` `{{url}}/api/v2/pam/jobs/3635` ``` { "data": { "job": { "id": "3635", "type": "rotate", "state": "canceled" } } } ``` O código de identificação do job é o mesmo código exibido para a operação na interface, em **Execuções** > **Operações de senha** > **Todas as operações**. Uma rotação aparece ali como uma operação **Troca de senha** com o tipo de credencial **Chave SSH**, no dispositivo principal da chave. Use essa tela para inspecionar uma rotação que não foi concluída. Nenhum artefato os define. A especificação nomeia apenas `queued`. A build foi observada retornando `canceled`. A interface exibe a operação correspondente como `Scheduled`, `Cancelled` ou `Error`, o que não usa a mesma grafia nem o mesmo vocabulário. O recurso de jobs é compartilhado no PAM Core e nenhum artefato o define. --- ## Erros A API v2 retorna um `code` estruturado no corpo da resposta, junto a uma `message` legível. | Código HTTP | Mensagem | Causa possível | Solução | | --- | --- | --- | --- | | `401` | `api.auth.token.invalid` | O token de acesso está ausente, expirado ou inválido. | Solicite um novo token de acesso e reenvie a requisição. | | `403` | `api.permission.denied` | A autorização não tem permissão de escrita nos recursos do PAM Core. | Peça ao administrador para verificar as permissões da autorização no A2A e gere um novo token. | | `404` | `api.resource.not_found` | A chave SSH 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_in_progress` | Já existe uma rotação em andamento para esta chave SSH. | Aguarde o job em execução terminar e envie a requisição novamente. | | `409` | `api.resource.inactive` | A chave SSH está inativa. Operações de escrita são rejeitadas em chaves inativas. | Ative a chave com [POST \| Ativar chave SSH](/v4-2/docs/api-v2-post-activate-ssh-key) e envie a requisição novamente. | | `429` | `rate_limit_exceeded` | O limite de requisições foi excedido. | Reduza a frequência das requisições e tente novamente. | | `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com o time de suporte da Segura™. | ### Exemplo de resposta de erro `409` já existe uma rotação em andamento: ``` { "code": "api.resource.conflict.rotation_in_progress", "message": "A change is already in progress for this SSH key.", "details": null } ``` Attention Na versão 4.2.13, uma rotação solicitada enquanto o message broker está indisponível cria o job, mas nunca o despacha. Quem fez a chamada recebe `500`, a chave SSH permanece bloqueada pelo job não despachado e não há nova tentativa automática. Verifique em **Execuções** > **Operações de senha** se há uma operação travada e cancele-a antes de solicitar uma nova rotação. A correção está prevista para a versão 4.2.15. Para as mensagens de erro de autenticação e a política de `403` versus `404`, acesse [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors). --- ## Documentos relacionados - [GET | Listar uma chave SSH por [id]](/v4-2/docs/api-v2-get-list-an-ssh-key) - [POST | Ativar chave SSH](/v4-2/docs/api-v2-post-activate-ssh-key) - [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)