POST | Check in credential

Description

Check a credential back in to PAM Core. Check-in releases the custody held by the calling application and revokes its access to the secret retrieved earlier. Access to that secret ends the moment the request succeeds.

Check-in is the counterpart of check-out: check-out takes the credential, check-in returns it. This endpoint is part of the A2A API v2 surface for credentials. The v1 equivalent is documented in DELETE | Release credential custody. For the concept of custody in PAM Core, access About credential custody.

Prerequisites

An application authorization granted by the administrator in A2A, with its PAM resource permission set to Read and write. For more information, access How to manage authorizations in A2A.
A valid OAuth 2.0 access token. For more information, access How to authenticate an application in A2A.
An active custody over the credential, held by the same application that sends the check-in request. A custody obtained by a user in the web interface does not satisfy this endpoint.

How the calling application obtains custody

API v2 has no check-out endpoint in this version. The application opens the custody through the v1 endpoint, which accepts the same OAuth 2.0 access token as v2, so the custody is opened in the name of the same application:

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

A successful call returns 200, opens the custody, and returns the credential secret.

Request

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

Path parameters

Field	Type	Required	Description
`id`	integer	Yes	Unique identification code of the credential. Note: this value is assigned by Segura®.

The request has no body.

Example request

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

Response

HTTP/1.1 204 No Content

The response has no body.

Automatic password change on return

When the credential is configured to change its password on return, check-in also starts an asynchronous password rotation. The 204 response does not carry a job reference, so the rotation cannot be tracked from this response. To follow a rotation the application started itself, use POST | Rotate credential instead.

Info

No endpoint reports whether a custody is currently open. An application can release a custody through the API, but cannot query for one before trying. Sending a check-in request and reading the response is the only way to establish the current state.

Errors

HTTP code	Message	Possible cause	Solution
`401`	`api.auth.token.invalid`	The access token is missing or has expired.	Request a new access token.
`403`	`api.permission.denied`	The authorization does not have permission to update credentials.	Ask the administrator to set the PAM resource permission to Read and write in A2A, then generate a new token.
`404`	`api.resource.not_found`	The credential does not exist, or it is outside the scope of the authorization.	Check the identification code sent in the path.
`409`	`api.resource.conflict.no_active_custody`	The calling application holds no custody over the credential, either because it never opened one or because it was already released.	Open the custody with the v1 endpoint before checking the credential in.
`429`	`rate_limit_exceeded`	The request rate limit was exceeded.	Reduce the request rate and try again.
`500`	`api.internal.error`	Internal server error.	Contact the Segura® support team.

Example error response

409 the calling application holds no custody:

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