--- title: "GET | Jobs de rotação" slug: "api-v2-get-rotation-jobs" updated: 2026-11-03T14:47:50Z published: 2026-11-03T14:47:50Z canonical: "docs.senhasegura.io/api-v2-get-rotation-jobs" --- > ## 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. # 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]](/v4-2/docs/pt/api-v2-post-rotate-credential) rotaciona a senha de uma credencial. - [POST | Rotate SSH key](/v4-2/docs/pt/api-v2-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](/v4-2/docs/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). - 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](/docs/pt/api-v2-get-rotation-jobs#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](/docs/pt/api-v2-get-rotation-jobs#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](/docs/pt/api-v2-get-rotation-jobs#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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).