GET | Jobs de rotação

Descrição

Acompanhe, cancele e reexecute uma rotação assíncrona no PAM Core. Quando você solicita uma rotação, o Segura™ a aceita, retorna 202 Accepted com um job e executa a rotação em segundo plano. O recurso de job informa o que aconteceu com essa rotação.

Dois endpoints criam jobs de rotação:

POST | Rotacionar credencial por [id] rotaciona a senha de uma credencial.
POST | Rotate SSH key rotaciona uma chave SSH.

Este documento cobre a consulta de um job e as duas ações que você pode executar sobre ele:

Operação	Endpoint
Consultar um job	`GET /api/v2/pam/jobs/{job-id}`
Cancelar uma rotação enfileirada	`POST /api/v2/pam/jobs/{job-id}/cancel`
Reexecutar uma rotação que falhou	`POST /api/v2/pam/jobs/{job-id}/retry`

Info

Um job registra a rotação em andamento e o resultado dela. Ele não é um histórico de rotações anteriores. O Segura™ expõe o histórico de rotações 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.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.
Um job criado por uma requisição de rotação. Você obtém o código de identificação do job na resposta 202 Accepted da rotação, em data.job.id e no cabeçalho de resposta Location.

Consultar um job

GET /api/v2/pam/jobs/{job-id}

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`job-id`	integer	Sim	Código de identificação único do job. O Segura™ o atribui quando aceita a rotação.

Exemplo de requisição

GET {{url}}/api/v2/pam/jobs/45

Resposta

HTTP/1.1 200 OK

Uma rotação concluída:

{
    "data": {
        "job": {
            "id": "45",
            "type": "rotate",
            "state": "succeeded",
            "retry_count": 1,
            "created_at": "2026-08-20T18:37:52-03:00",
            "started_at": "2026-08-20T15:37:54-03:00",
            "finished_at": "2026-08-20T15:39:11-03:00",
            "related_resource": {
                "type": "credential",
                "id": "102"
            }
        }
    }
}

Uma rotação que falhou traz o motivo em error:

{
    "data": {
        "job": {
            "id": "51",
            "type": "rotate",
            "state": "failed",
            "retry_count": 1,
            "created_at": "2026-08-20T19:58:06-03:00",
            "started_at": "2026-08-20T16:58:11-03:00",
            "finished_at": "2026-08-20T16:58:24-03:00",
            "related_resource": {
                "type": "credential",
                "id": "1"
            },
            "error": {
                "code": "pam.rotation.execution_failed",
                "message": "Credential does not have a template configured for this operation."
            }
        }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	Envelope da resposta.
`data.job`	object	O job de rotação. Veja a tabela a seguir.

`job`

Campo	Tipo	Descrição
→`id`	string	Código de identificação único do job.
→`type`	string	Tipo do job. `rotate` para uma rotação.
→`state`	string	Estado atual do job. Valores permitidos: `queued`, `running`, `succeeded`, `failed`, `canceled`. Veja Estados do job.
→`retry_count`	integer	Número de tentativas registradas para este job.
→`created_at`	string	Data e hora de criação do job, no formato ISO 8601. Veja Problemas conhecidos.
→`started_at`	string	Data e hora em que a rotação começou a ser executada, no formato ISO 8601. Vazio enquanto o job está em `queued` e para um job cancelado antes de começar.
→`finished_at`	string	Data e hora em que a rotação parou de ser executada, no formato ISO 8601. Preenchido para jobs `succeeded` e `failed`. Vazio para jobs `canceled` e enquanto o job está em `queued` ou `running`.
→`related_resource`	object	O recurso sobre o qual a rotação atua.
→→`type`	string	Tipo do recurso de origem. `credential` para a rotação de uma credencial. Veja Problemas conhecidos para o caminho de chave SSH.
→→`id`	string	Código de identificação único do recurso de origem.
→`error`	object	Presente apenas quando `state` é `failed`.
→→`code`	string	Código de falha legível por máquina. Exemplo: `pam.rotation.execution_failed`.
→→`message`	string	Descrição da falha. Exemplos: `Credential does not have a template configured for this operation.`, `Automatic change disabled.`

Estados do job

Estado	Terminal	Descrição
`queued`	Não	A rotação foi aceita e aguarda para começar. Você pode cancelar o job enquanto ele está neste estado.
`running`	Não	A troca da senha ou da chave está em andamento no dispositivo de destino.
`succeeded`	Sim	A troca foi aplicada no dispositivo e armazenada no cofre.
`failed`	Sim	A rotação foi executada e não foi concluída. O objeto `error` traz o motivo.
`canceled`	Sim	A rotação foi cancelada antes de começar. Nenhuma troca foi tentada.

Atenção

Uma rotação não tem timeout documentado. Se o dispositivo de destino estiver inacessível, o job pode permanecer em running por muito tempo, e o recurso de origem fica bloqueado para novas rotações enquanto isso durar. Não escreva um laço de consulta que suponha a chegada de um estado terminal dentro de uma janela fixa.

Cancelar uma rotação enfileirada

POST /api/v2/pam/jobs/{job-id}/cancel

Cancela uma rotação que ainda não começou. O job passa para canceled e nenhuma troca é tentada no dispositivo.

HTTP/1.1 200 OK

{
    "data": {
        "job": {
            "id": "48",
            "type": "rotate",
            "state": "canceled",
            "retry_count": 0,
            "created_at": "2026-08-20T19:57:13-03:00",
            "started_at": null,
            "finished_at": null,
            "related_resource": {
                "type": "credential",
                "id": "102"
            }
        }
    }
}

Atenção

Você pode cancelar uma rotação apenas enquanto o job está em queued. Depois que o job está em running, a troca já está em andamento no dispositivo e não pode ser revertida.

Reexecutar uma rotação que falhou

POST /api/v2/pam/jobs/{job-id}/retry

Solicita uma nova tentativa para uma rotação que terminou em failed.

Apenas um job em failed pode ser reexecutado. Qualquer outro estado retorna 409 com o código api.job.invalid_transition:

{
    "error": {
        "code": "api.job.invalid_transition",
        "message": "Only a failed rotation can be retried.",
        "details": {
            "state": "running"
        }
    }
}

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.
`404`	`api.resource.not_found`	O job não existe ou está fora do escopo da autorização.	Verifique o código de identificação enviado no caminho.
`409`	`api.job.invalid_transition`	A ação não é válida para o estado atual do job, por exemplo reexecutar um job que não está em `failed`.	Consulte o job e verifique o `state` dele antes de enviar a açã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™.

Info

Um job fora do escopo da sua autorização retorna 404, o mesmo status de um job que não existe. Não é possível distinguir os dois casos, e isso é intencional.

Problemas conhecidos

Estes afetam o recurso de job nesta versão.

Campo	Comportamento	Registrado como
`created_at`	No job de rotação de uma credencial, o valor é a hora UTC com o offset `-03:00`, portanto resolve três horas à frente da hora real de criação e pode aparecer depois de `started_at`. O caminho de chave SSH está correto.	SSGR-11972
`related_resource.type`	Um job criado pela rotação de uma chave SSH informa `credential` em vez de um tipo que identifique uma chave SSH. O `id` está correto. Resolver `type` mais `id` pode, portanto, levar ao recurso errado, porque uma credencial e uma chave SSH podem ter o mesmo código de identificação.	SSGR-11909
`finished_at`	Vazio em um job `canceled`, mesmo com o job em estado terminal.	SSGR-11997

Use started_at e finished_at para medir tempos e trate created_at como não confiável para ordenação.

Para mensagens de erros de autenticação e o formato de erro compartilhado, acesse API v2 - Convenções e comportamentos compartilhados.