Skip to main content
POST
/
v1
/
attestations
/
{id}
/
supersede
Supersede Attestation
curl --request POST \
  --url https://api.truthlocks.com/v1/attestations/{id}/supersede \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "payload": {
    "subject": "user:12345",
    "claim": "verified_email",
    "value": "newemail@example.com"
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "issuer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kid": "<string>",
  "payload": {},
  "signature": "<string>",
  "log_index": 123,
  "created_at": "2023-11-07T05:31:56Z"
}
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.

​
How it works

1

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.
2

Original attestation marked SUPERSEDED

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

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.
4

Both returned in response

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

​
Parameters

​
id
uuid
required
The UUID of the original attestation to supersede. Must be in VALID status.
​
payload_b64url
string
required
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.
​
kid
string
required
Key identifier for the signing key to use for the new attestation. Can be the same key as the original or a different one (for example, after key rotation).
​
alg
string
required
Cryptographic algorithm for signing the new attestation. Must match the key type of the specified kid.
​
Idempotency-Key
string
required
Ensures safe retries in case of network failures. Reusing the same key with the same parameters returns the original response without creating a duplicate.

​
Common use cases

Use caseScenarioExample
Credential updateEmployee changes role or departmentSupersede old employment verification with updated title
RenewalCertificate or license expires and is renewedSupersede expired medical license with new expiry date
Error correctionTypo or incorrect data in original credentialSupersede passport attestation with corrected name
Version upgradeSchema or claims format changesSupersede v1 credential with v2 format
Key rotationSigning key compromised or rotatedSupersede attestation signed with old key using new key

​
Responses

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.
The original attestation remains in the transparency log and can still be verified. Its status changes to SUPERSEDED but the cryptographic proof is preserved. Verifiers can trace the full supersession chain by following the superseded_by_attestation_id field.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Path Parameters

​
id
string<uuid>
required

Body

application/json
​
payload
object
required

Updated payload for the new attestation

Response

201 - application/json

New attestation created

​
id
string<uuid>
​
issuer_id
string<uuid>
​
kid
string
​
status
enum<string>
Available options:
VALID,
REVOKED,
SUPERSEDED
​
payload
object
​
signature
string
​
log_index
integer
​
created_at
string<date-time>