paperclip_rotate_secret
Rotate a secret's value, incrementing its version to replace compromised or expiring credentials while preserving previous references.
Instructions
⚠ Board-only: Rotate a secret's value, incrementing its version. Increments the secret version (v1 → v2 → v3). Previous references to the secret remain valid for older versions unless specifically purged.
Args:
secretId: string — Secret UUID
value: string — New secret value (stored encrypted, never returned)
externalRef: string | null (optional) — Updated external reference after rotation (null to clear)
Returns: Updated secret metadata with incremented latestVersion: id, companyId, name, provider, externalRef, latestVersion, description, timestamps. Value is never returned.
Examples:
Use when: rotating a compromised or expiring credential; each call increments latestVersion
Don't use when: you only need to rename or update metadata without changing the value — use paperclip_update_secret instead
Error Handling:
404: secret not found → verify secretId with paperclip_list_secrets
401: authentication failed → check PAPERCLIP_API_KEY
403: permission denied → this tool requires a board (human-user) API key
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| secretId | Yes | Secret UUID | |
| value | Yes | New secret value — increments the version | |
| externalRef | No | New external reference after rotation (null to clear) |