POST | Rotate SSH key

Description

Renew an SSH key pair in PAM Core. The platform generates a new pair and replaces the existing key on the main device associated with the record.

Rotation is asynchronous, because it connects to the main device to perform the exchange. The endpoint returns 202 Accepted with a job, not the finished result. The rotation follows the key_renewal settings of the SSH key, which you can read with GET | List an SSH key by [id].

Alert

Rotation replaces the key material on the target device. Any system still using the previous private key loses access once the exchange completes. Confirm which consumers depend on the key before you rotate it.

Prerequisites

Authorization with read and write permission to PAM Core, granted by the administrator in A2A. 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.
The SSH key must be active. Rotating an inactive key returns 409.
The SSH key must have a main device, and the platform must be able to reach it.

Request

POST /api/v2/pam/ssh-keys/{id}/rotate

Path parameters

Field	Type	Required	Description
`id`	string	Yes	Unique identification code of the SSH key, assigned by Segura®.

The request has no body.

Example request

POST {{url}}/api/v2/pam/ssh-keys/2267/rotate

Response

HTTP/1.1 202 Accepted

Example response body

{
    "data": {
        "job": {
            "id": "3635",
            "type": "rotate",
            "state": "queued"
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/pam/jobs/3635"
        }
    }
}

Response body fields

Field	Type	Description
`data.job`	object	The asynchronous job created for this rotation.
`data.job.id`	string	Unique identification code of the job.
`data.job.type`	string	Type of the job. Always `rotate` for this endpoint.
`data.job.state`	string	Current state of the job. A newly created job is `queued`.
`meta.links.self`	string	URL of the job resource, used to follow the rotation.

Following the job

Send a GET request to the URL in meta.links.self to read the current state of the rotation:

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

{
    "data": {
        "job": {
            "id": "3635",
            "type": "rotate",
            "state": "canceled"
        }
    }
}

The job identification code is the same code shown for the operation in the interface, under Executions > Password operations > All operations. A rotation appears there as a Change password operation with the credential type SSH key, against the main device of the key. Use that screen to inspect a rotation that did not complete.

No artifact defines them. The specification names only queued. The build was observed returning canceled. The interface shows the matching operation as Scheduled, Cancelled, or Error, which does not use the same spelling or the same vocabulary. The jobs resource is shared across PAM Core and no artifact defines it.

Errors

API v2 returns a structured code in the response body, alongside a human-readable message.

HTTP code	Message	Possible cause	Solution
`401`	`api.auth.token.invalid`	The access token is missing, expired, or invalid.	Request a new access token and resend the request.
`403`	`api.permission.denied`	The authorization does not have write permission to PAM Core resources.	Ask the administrator to check the authorization permissions in A2A, then generate a new token.
`404`	`api.resource.not_found`	The SSH key does not exist, or it is outside the scope of the authorization.	Check the identification code sent in the path.
`409`	`api.resource.conflict.rotation_in_progress`	A rotation is already running for this SSH key.	Wait for the running job to finish, then send the request again.
`409`	`api.resource.inactive`	The SSH key is inactive. Write operations are rejected on inactive keys.	Activate the key with POST \| Activate SSH key, then send the request again.
`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 a rotation is already running:

{
    "code": "api.resource.conflict.rotation_in_progress",
    "message": "A change is already in progress for this SSH key.",
    "details": null
}

Attention

In version 4.2.13, a rotation requested while the message broker is unavailable creates the job but never dispatches it. The caller receives 500, the SSH key stays locked by the undispatched job, and no automatic retry occurs. Check Executions > Password operations for a stuck operation and cancel it before requesting a new rotation. A fix is scheduled for version 4.2.15.

For authentication error messages and the 403 versus 404 policy, access API v2 - Conventions and shared behaviors.