REST API · keys
POST /keys/{id}/reveal-successor
One-shot plaintext retrieval for an auto-minted successor. Returns 410 when the secret has already been revealed (or was never stored, e.g.
a manually-rotated key) — the plaintext is genuinely unrecoverable.
post_api_keys_reveal_successor
Authentication
- Bearer
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
| id | path | yes | {"type":"string"} |
Responses
200
The successor key and its one-shot plaintext.
application/json
{
"key": {
"id": "f6a7b8c9-0d1e-4f6a-a17c-4d5e6f7a8b9c",
"name": "Production key",
"mode": "live",
"prefix": "er_live_9a2c8b1d",
"createdAt": "2026-01-20T09:00:00+00:00",
"createdBy": "owner@example.com",
"lastUsedAt": null,
"expiresAt": "2026-04-20T09:00:00+00:00",
"revokedAt": null,
"successorId": null,
"predecessorId": "e5f6a7b8-9c0d-4e5f-b06b-3c4d5e6f7a8b",
"successorRevealedAt": null
},
"plaintext": "er_live_9a2c8b1d6e3f7a0b5c9d2e8f1a3b6c4d7e0f2a1b5c8d3e4f"
}401
No authenticated user for this token.
application/json
{
"required": [
"error"
],
"properties": {
"error": {
"description": "Machine-readable error code, e.g. \"not_found\", \"forbidden\", \"validation\".",
"type": "string",
"enum": [
"bad_request",
"unauthorized",
"insufficient_credits",
"forbidden",
"web_only",
"allowlist_widens",
"not_found",
"conflict",
"draft_revision_conflict",
"rollback_confirmation_conflict",
"not_replayable",
"targets_outside_allowlist",
"gone",
"deprecated_operation",
"validation",
"rate_limited",
"payment_provider",
"verification_unavailable",
"analytics_unavailable",
"credential_vault_unavailable",
"notification_grants_unavailable"
]
},
"message": {
"description": "Human-readable explanation of what went wrong. Absent on a field-level validation failure, where `fields` carries the detail instead.",
"type": "string"
},
"object": {
"description": "The resource the error concerns, when there is one.",
"required": [
"type",
"id"
],
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
}
},
"type": "object"
},
"action": {
"description": "What to do next, naming the call or the panel page that does it. Absent when there is no corrective step.",
"type": "string"
},
"fields": {
"description": "Present when `error` is \"validation\" — one message per rejected field, keyed by the field name.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"retry_after": {
"description": "An RFC 3339 timestamp, the moment the request may be retried. Not every `rate_limited` refusal carries one.",
"type": "string",
"format": "date-time"
}
},
"type": "object"
}404
Key not found.
application/json
{
"required": [
"error"
],
"properties": {
"error": {
"description": "Machine-readable error code, e.g. \"not_found\", \"forbidden\", \"validation\".",
"type": "string",
"enum": [
"bad_request",
"unauthorized",
"insufficient_credits",
"forbidden",
"web_only",
"allowlist_widens",
"not_found",
"conflict",
"draft_revision_conflict",
"rollback_confirmation_conflict",
"not_replayable",
"targets_outside_allowlist",
"gone",
"deprecated_operation",
"validation",
"rate_limited",
"payment_provider",
"verification_unavailable",
"analytics_unavailable",
"credential_vault_unavailable",
"notification_grants_unavailable"
]
},
"message": {
"description": "Human-readable explanation of what went wrong. Absent on a field-level validation failure, where `fields` carries the detail instead.",
"type": "string"
},
"object": {
"description": "The resource the error concerns, when there is one.",
"required": [
"type",
"id"
],
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
}
},
"type": "object"
},
"action": {
"description": "What to do next, naming the call or the panel page that does it. Absent when there is no corrective step.",
"type": "string"
},
"fields": {
"description": "Present when `error` is \"validation\" — one message per rejected field, keyed by the field name.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"retry_after": {
"description": "An RFC 3339 timestamp, the moment the request may be retried. Not every `rate_limited` refusal carries one.",
"type": "string",
"format": "date-time"
}
},
"type": "object"
}409
This key has no successor to reveal.
application/json
{
"required": [
"error"
],
"properties": {
"error": {
"description": "Machine-readable error code, e.g. \"not_found\", \"forbidden\", \"validation\".",
"type": "string",
"enum": [
"bad_request",
"unauthorized",
"insufficient_credits",
"forbidden",
"web_only",
"allowlist_widens",
"not_found",
"conflict",
"draft_revision_conflict",
"rollback_confirmation_conflict",
"not_replayable",
"targets_outside_allowlist",
"gone",
"deprecated_operation",
"validation",
"rate_limited",
"payment_provider",
"verification_unavailable",
"analytics_unavailable",
"credential_vault_unavailable",
"notification_grants_unavailable"
]
},
"message": {
"description": "Human-readable explanation of what went wrong. Absent on a field-level validation failure, where `fields` carries the detail instead.",
"type": "string"
},
"object": {
"description": "The resource the error concerns, when there is one.",
"required": [
"type",
"id"
],
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
}
},
"type": "object"
},
"action": {
"description": "What to do next, naming the call or the panel page that does it. Absent when there is no corrective step.",
"type": "string"
},
"fields": {
"description": "Present when `error` is \"validation\" — one message per rejected field, keyed by the field name.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"retry_after": {
"description": "An RFC 3339 timestamp, the moment the request may be retried. Not every `rate_limited` refusal carries one.",
"type": "string",
"format": "date-time"
}
},
"type": "object"
}410
Already revealed, or no stored plaintext for this key.
application/json
{
"required": [
"error"
],
"properties": {
"error": {
"description": "Machine-readable error code, e.g. \"not_found\", \"forbidden\", \"validation\".",
"type": "string",
"enum": [
"bad_request",
"unauthorized",
"insufficient_credits",
"forbidden",
"web_only",
"allowlist_widens",
"not_found",
"conflict",
"draft_revision_conflict",
"rollback_confirmation_conflict",
"not_replayable",
"targets_outside_allowlist",
"gone",
"deprecated_operation",
"validation",
"rate_limited",
"payment_provider",
"verification_unavailable",
"analytics_unavailable",
"credential_vault_unavailable",
"notification_grants_unavailable"
]
},
"message": {
"description": "Human-readable explanation of what went wrong. Absent on a field-level validation failure, where `fields` carries the detail instead.",
"type": "string"
},
"object": {
"description": "The resource the error concerns, when there is one.",
"required": [
"type",
"id"
],
"properties": {
"type": {
"type": "string"
},
"id": {
"type": "string"
}
},
"type": "object"
},
"action": {
"description": "What to do next, naming the call or the panel page that does it. Absent when there is no corrective step.",
"type": "string"
},
"fields": {
"description": "Present when `error` is \"validation\" — one message per rejected field, keyed by the field name.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"retry_after": {
"description": "An RFC 3339 timestamp, the moment the request may be retried. Not every `rate_limited` refusal carries one.",
"type": "string",
"format": "date-time"
}
},
"type": "object"
}