Supersede Attestation

POSThttps://sandbox-api.truthlocks.com/v1/attestations/{id}/supersedeAuth required

Creates a new attestation that supersedes an existing one. The original attestation is marked as SUPERSEDED with a reference to the new version. The new attestation is signed with the specified key, recorded in the transparency log, and returned alongside the updated original. Both attestations remain verifiable, creating an auditable chain of credential versions. Only VALID attestations can be superseded — REVOKED or already SUPERSEDED attestations return a 409 Conflict.

Path Parameters

iduuidrequired

The UUID of the original attestation to supersede. Must be in VALID status.

Defaults to 660e8400-e29b-41d4-a716-446655440001

Header Parameters

Idempotency-Keystringrequired

Ensures safe retries in case of network failures. Reusing the same key with the same parameters returns the original response without creating a duplicate.

Defaults to supersede_key_abc123

Body Parameters

payload_b64urlstringrequired

Base64url-encoded payload for the new attestation. This replaces the content of the original. For JSON claims, base64url-encode the JSON string. For documents, base64url-encode the file bytes.

Defaults to eyJzdWJqZWN0IjoidXNlcjoxMjM0NSIsImNsYWltIjoidmVyaWZpZWRfZW1haWwiLCJ2YWx1ZSI6InVwZGF0ZWRAZXhhbXBsZS5jb20iLCJzdXBlcnNlc3Npb25fcmVhc29uIjoiRW1haWwgYWRkcmVzcyBjaGFuZ2VkIn0

kidstringrequired

Key identifier for the signing key to use for the new attestation. Can be the same key as the original or a different one (e.g. after key rotation).

Defaults to ed-key-1

algstringrequired

Cryptographic algorithm for signing the new attestation. Must match the key type of the specified kid.

Defaults to Ed25519

Responses

{
  "old": {
    "attestation_id": "660e8400-e29b-41d4-a716-446655440001",
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "kid": "ed-key-1",
    "status": "SUPERSEDED",
    "superseded_at": "2026-03-07T15:00:00Z",
    "superseded_by_attestation_id": "770e8400-e29b-41d4-a716-446655440002",
    "payload_hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd",
    "log_index": 1056,
    "created_at": "2026-02-18T19:00:00Z"
  },
  "new": {
    "attestation_id": "770e8400-e29b-41d4-a716-446655440002",
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "kid": "ed-key-1",
    "alg": "Ed25519",
    "status": "VALID",
    "payload_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "signature": "U2lnbmF0dXJl...",
    "log_index": 1057,
    "created_at": "2026-03-07T15:00:00Z"
  }
}

Supersede Workflow

Supersession creates a verifiable chain of credential versions. The original attestation is marked as SUPERSEDED and linked to the new replacement attestation. Both remain in the transparency log for full auditability.

How it works

Call supersede with original attestation ID

Provide the UUID of the attestation to supersede as a path parameter, along with the new payload and signing key.

Original attestation marked SUPERSEDED

The original attestation’s status changes to SUPERSEDED with a timestamp and a reference to the new attestation ID.

New attestation created with VALID status

A new attestation is minted with the updated payload, signed with the specified key, and recorded in the transparency log.

Both returned in response

The response includes both the old (superseded) and new (valid) attestation objects under "old" and "new" keys.

Common Use Cases

Use Case	Scenario	Example
Credential Update	Employee changes role or department	Supersede old employment verification with updated title and department
Renewal	Certificate or license expires and is renewed	Supersede expired medical license with new expiry date
Error Correction	Typo or incorrect data in original credential	Supersede passport attestation with corrected name spelling
Version Upgrade	Schema or claims format changes	Supersede v1 credential with v2 format including new required fields
Key Rotation	Signing key compromised or rotated	Supersede attestation signed with old key using new signing key

Important Notes

Idempotency: Supersede operations are idempotent when using the same Idempotency-Key. Retrying a failed request with the same key is safe and will not create duplicate attestations.

Immutability: The original attestation remains in the transparency log and can still be verified. Its status changes to SUPERSEDED but the cryptographic proof is preserved.

Chain Verification: Verifiers can trace the full supersession chain by following the superseded_by field on the original attestation to find the current valid version.

Status Restrictions: Only VALID attestations can be superseded. Attempting to supersede a REVOKED or already SUPERSEDED attestation returns a 409 Conflict error.

POST/v1/attestations/{id}/supersede

Language

CredentialsHEADER

Authorization

cURL Request

Examples ▾

curl --request POST \
  --url https://sandbox-api.truthlocks.com/v1/attestations/660e8400-e29b-41d4-a716-446655440001/supersede \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
  "payload_b64url": "eyJzdWJqZWN0IjoidXNlcjoxMjM0NSIsImNsYWltIjoidmVyaWZpZWRfZW1haWwiLCJ2YWx1ZSI6InVwZGF0ZWRAZXhhbXBsZS5jb20iLCJzdXBlcnNlc3Npb25fcmVhc29uIjoiRW1haWwgYWRkcmVzcyBjaGFuZ2VkIn0",
  "kid": "ed-key-1",
  "alg": "Ed25519"
}'

Response

Click Try It! to send a real request, or view sample responses: