---
title: "POST | Rotate credential by [id]"
slug: "api-v2-post-rotate-credential"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-post-rotate-credential"
---

> ## 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 credential by [id]

## 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](/v4-2/docs/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](/docs/api-v2-post-rotate-credential#track-the-rotation-job).

              Info

              

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](/v4-2/docs/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:rotate` scope. For more information, access [How to authenticate an application in A2A](/v4-2/docs/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`.

              Info

              

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](/v4-2/docs/api-v2-get-rotation-jobs). |
| →`created_at` | string | Date and time the job was created, in ISO 8601 format. See the known issues in [Rotation jobs](/v4-2/docs/api-v2-get-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](/v4-2/docs/api-v2-get-rotation-jobs).

              Info

              

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"
                }
            }
        }
    }
}
```

              Attention

              

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.

              Info

              

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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).