# Rotate a credential secret

`POST https://api.cademi.com.br/api/v3/credentials/{credential_id}/secret-rotations`

Operation ID: `credentials.secret_rotations.create` · API v3

Generates a new secret for the credential. The credential ID and its policies do not change.

The previous secret remains valid for an overlap period, set by `overlap_hours` (1 to 168 hours, default 24), so integrations can switch to the new secret without downtime.

The new secret is returned only in this response and cannot be retrieved again. Store it securely.

Required permissions: `credentials.manage`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `credential_id` | path | string | yes |  |
| `Idempotency-Key` | header | string | yes |  |

## Request body

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `overlap_hours` | integer or null | no |  |

## Responses

### 201

Returns the new secret. The secret is not returned by any other operation.

Body: `data`: SecretRotation.

Fields of SecretRotation:

| Field | Type | Required | Description |
|---|---|---|---|
| `object` | string, one of `secret_rotation` | yes |  |
| `rotated_at` | string (date-time) | yes |  |
| `secret` | string | yes |  |

### 401

The credential is missing, malformed, expired, or revoked.

Body: Error.

### 403

The current credentials do not have the permission required by this operation.

Body: Error.

### 404

The credential was not found or is not accessible with the current credentials.

Body: Error.

### 422

The request body or query parameters failed validation.

Body: ValidationFailed.

Full schema: https://cademi.dev/openapi/v3.json