Rotate a Secret
Rotates a secret by marking the existing secret as ROTATED and generating a new active secret in its place. The old secret immediately becomes invalid.
POST /v1/recipients/:recipientId/secrets/:secretId/rotate
Path Parameters
| Parameter | Type | Description |
|---|
recipientId | string | The recipient ID |
secretId | string | The secret ID to rotate |
Example Request
curl -X POST https://api.docyard.io/v1/recipients/rcp_01HQ3N.../secrets/sec_01HQ5A.../rotate \
-H "Authorization: Bearer dk_live_a1b2c3d4..."
Response
{
"id": "sec_01HQ5D...",
"secret": "dys_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4"
}
Error Handling
| Status | Condition |
|---|
401 | Missing or invalid API key |
404 | Recipient or secret not found |
409 | Secret has already been rotated or revoked |
The new secret value is shown only once in this response. The old secret is immediately marked as ROTATED and can no longer be used for verification. Update your systems with the new secret before discarding this response.
