--- title: "POST | Rotate SSH key" slug: "api-v2-post-rotate-ssh-key" updated: 2026-11-03T14:47:51Z published: 2026-11-03T14:47:51Z canonical: "docs.senhasegura.io/api-v2-post-rotate-ssh-key" --- > ## 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. # 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]](/v4-2/docs/api-v2-get-list-an-ssh-key). 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](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a). - A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/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](/v4-2/docs/api-v2-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](/v4-2/docs/api-v2-conventions-and-shared-behaviors). --- ## Related documents - [GET | List an SSH key by [id]](/v4-2/docs/api-v2-get-list-an-ssh-key) - [POST | Activate SSH key](/v4-2/docs/api-v2-post-activate-ssh-key) - [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors)