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].

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.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação 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 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.