Description
Request an immediate password rotation for a single credential in PAM Core, outside the credential's scheduled rotation cycle. The main use case is incident response, when a suspected compromise requires rotating a credential now instead of waiting for the next cycle.
This endpoint exposes the same on-demand rotation that is already available in the interface. For the interface equivalent, access How to request a password change from the credentials list.
Rotation is asynchronous. Changing a password on a target device is not instantaneous and can fail, so the request returns 202 Accepted as soon as the rotation is accepted, and the rotation itself runs in the background. The response carries a reference to a job, which you poll to find out what happened. See Track the rotation job.
This endpoint reports only the rotation it started. It does not return the history of past rotations for a credential. Segura® exposes that history through the per-credential audit trail, which is documented separately.
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.
- An access policy that grants the application access to the credential you want to rotate.
- A valid OAuth 2.0 access token carrying the
credentials:rotatescope. For more information, access How to authenticate an application in A2A. - The credential must have a change template configured. A credential without one is accepted, but its rotation job ends in
failed.
An access token carries only the authorizations that existed when it was generated. After the administrator changes the application's permissions, generate a new token, an existing token won't gain the new authorization.
Request
POST /api/v2/pam/credentials/{id}/rotate
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
id |
integer | Yes | Unique identification code of the credential to rotate. |
The request has no body.
Example request
POST {{url}}/api/v2/pam/credentials/102/rotate
Response
HTTP/1.1 202 Accepted
{
"data": {
"job": {
"id": "48",
"type": "rotate",
"state": "queued",
"created_at": "2026-08-20T16:57:13-03:00",
"related_resource": {
"type": "credential",
"id": "102"
}
}
}
}
A 202 Accepted means the rotation was accepted and queued, not that the password changed. Poll the job to find out whether it completed.
Response body fields
| Field | Type | Description |
|---|---|---|
data |
object | Response envelope. |
data.job |
object | The rotation job created by this request. See the following table. |
job
| Field | Type | Description |
|---|---|---|
→id |
string | Unique identification code of the job. Use it to poll, cancel, or retry the rotation. |
→type |
string | Job type. Always rotate for this endpoint. |
→state |
string | Current state of the job. Allowed values: queued, running, succeeded, failed, canceled. See Rotation jobs. |
→created_at |
string | Date and time the job was created, in ISO 8601 format. See the known issues in Rotation jobs. |
→related_resource |
object | The resource the job acts on. |
→→type |
string | Resource type. credential for rotations started by this endpoint. |
→→id |
string | Unique identification code of the credential being rotated. |
Track the rotation job
Read the job to find out whether the rotation completed:
GET /api/v2/pam/jobs/{job-id}
A rotation job passes through five states — queued, running, succeeded, failed and canceled. While the job is queued you can cancel it; once it has ended in failed you can request a new attempt. A job that fails carries the reason in an error object.
For the full job contract, the state table, and the cancel and retry actions, access Rotation jobs.
A 202 Accepted means the rotation was accepted and queued, not that the password changed. Always confirm the outcome by reading the job.
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.auth.forbidden |
The application is not authorized for this credential. | Ask the administrator to check the application's PAM Core permission and the access policy covering this credential, then generate a new token. |
404 |
api.resource.not_found |
The credential doesn't exist, or it's outside the scope of the authorization. | Check the identification code sent in the path. |
409 |
api.resource.conflict.rotation_pending |
A rotation is already in progress for this credential. | Track the job named in details.job instead of sending 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 in progress:
{
"error": {
"code": "api.resource.conflict.rotation_pending",
"message": "A rotation is already in progress for this credential.",
"details": {
"job": {
"id": "48",
"type": "rotate",
"links": {
"self": "/api/v2/pam/jobs/48"
}
}
}
}
}
A 409 is expected behavior, not a defect. Segura® refuses a second rotation on a credential that is already rotating, because two rotations racing to set the same device password can leave the vault and the device out of step.
The 409 also fires when Segura® itself started the rotation, for example when a privileged session ends or a credential's custody is returned. An automation can therefore receive 409 without having requested anything. Read details.job to find the rotation already in progress and track that job, rather than retrying.
The rotation lock applies per credential, not globally. A 409 on one credential does not stop you rotating a different one.
For authentication error messages and the shared 403 and 404 rules, access API v2 - Conventions and shared behaviors.