POST | Fazer check-in de credencial

Descrição

Faça o check-in de uma credencial no PAM Core. O check-in libera a custódia detida pela aplicação chamadora e revoga o acesso dela ao segredo obtido antes. O acesso a esse segredo termina no momento em que a requisição é bem-sucedida.

O check-in é a contrapartida do check-out: o check-out retira a credencial, o check-in a devolve. Este endpoint faz parte da superfície da API v2 do A2A para credenciais. O equivalente na v1 está documentado em DELETE | Liberar custódia de credencial. Para o conceito de custódia no PAM Core, acesse Sobre a custódia de credenciais.

Pré-requisitos

Uma autorização de aplicação concedida pelo administrador no A2A, com a permissão de recurso do PAM definida como Leitura e escrita. 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 no A2A.
Uma custódia ativa sobre a credencial, detida pela mesma aplicação que envia a requisição de check-in. Uma custódia obtida por um usuário na interface web não atende a este endpoint.

Como a aplicação chamadora obtém a custódia

A API v2 não tem endpoint de check-out nesta versão. A aplicação abre a custódia pelo endpoint da v1, que aceita o mesmo token de acesso OAuth 2.0 da v2, então a custódia é aberta em nome da mesma aplicação:

GET {{url}}/api/pam/credential/12

Uma chamada bem-sucedida retorna 200, abre a custódia e devolve o segredo da credencial.

Requisição

POST /api/v2/pam/credentials/{id}/checkin

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Código único de identificação da credencial. Nota: este valor é atribuído pelo Segura®.

A requisição não tem corpo.

Exemplo de requisição

POST {{url}}/api/v2/pam/credentials/12/checkin

Resposta

HTTP/1.1 204 No Content

A resposta não tem corpo.

Troca automática de senha na devolução

Quando a credencial está configurada para trocar a senha na devolução, o check-in também inicia uma rotação de senha assíncrona. A resposta 204 não traz referência de job, então a rotação não pode ser acompanhada a partir dessa resposta. Para acompanhar uma rotação que a própria aplicação iniciou, use POST | Rotacionar credencial.

Info

Nenhum endpoint informa se existe uma custódia aberta. Uma aplicação pode liberar uma custódia pela API, mas não pode consultar se existe uma antes de tentar. Enviar a requisição de check-in e ler a resposta é a única forma de estabelecer o estado atual.

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.permission.denied`	A autorização não tem permissão para atualizar credenciais.	Peça ao administrador para definir a permissão de recurso do PAM como Leitura e escrita no A2A 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.no_active_custody`	A aplicação chamadora não detém custódia sobre a credencial, porque nunca abriu uma ou porque ela já foi liberada.	Abra a custódia pelo endpoint da v1 antes de fazer o check-in da credencial.
`429`	`rate_limit_exceeded`	O limite de requisições foi excedido.	Reduza a taxa de requisições e tente novamente.
`500`	`api.internal.error`	Erro interno do servidor.	Entre em contato com o time de suporte do Segura®.

Exemplo de resposta de erro

409 a aplicação chamadora não detém custódia:

{
    "error": {
        "code": "api.resource.conflict.no_active_custody",
        "message": "No active custody held by this application for the credential.",
        "details": null
    }
}

Documentos relacionados

Para as mensagens de erro de autenticação, a política de 403 versus 404 e os limites atuais do bloco meta.actions, acesse API v2 - Convenções e comportamentos compartilhados.