> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supersede Attestation

> Creates a new attestation that supersedes an existing one.
The original attestation is marked as SUPERSEDED.


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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Original attestation marked SUPERSEDED">
    The original attestation's status changes to `SUPERSEDED` with a timestamp and a reference to the new attestation ID.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Both returned in response">
    The response includes both the old (superseded) and new (valid) attestation objects under `old` and `new` keys.
  </Step>
</Steps>

### Parameters

<ParamField path="id" type="uuid" required>
  The UUID of the original attestation to supersede. Must be in `VALID` status.
</ParamField>

<ParamField body="payload_b64url" type="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.
</ParamField>

<ParamField body="kid" type="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).
</ParamField>

<ParamField body="alg" type="string" required>
  Cryptographic algorithm for signing the new attestation. Must match the key type of the specified `kid`.
</ParamField>

<ParamField header="Idempotency-Key" type="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.
</ParamField>

### Common use cases

| Use case          | Scenario                                      | Example                                                  |
| ----------------- | --------------------------------------------- | -------------------------------------------------------- |
| Credential update | Employee changes role or department           | Supersede old employment verification with updated title |
| 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       |
| Version upgrade   | Schema or claims format changes               | Supersede v1 credential with v2 format                   |
| Key rotation      | Signing key compromised or rotated            | Supersede attestation signed with old key using new key  |

### Responses

<Info>
  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.
</Info>

<Warning>
  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.
</Warning>


## OpenAPI

````yaml mint-openapi.yaml POST /v1/attestations/{id}/supersede
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks is a universal verification infrastructure for documents,
    credentials, and digital assets.

    This specification defines the canonical API for interacting with Truthlocks
    services.


    ## Base URLs

    - **Production**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentication

    - **API Keys**: Use `X-API-Key` header for machine-to-machine operations

    - **Bearer Tokens**: Use `Authorization: Bearer <jwt>` for user-initiated
    operations


    ## Tenant Identity

    In production, tenant identity is derived from the authenticated context
    (API key or JWT).

    The `X-Tenant-ID` header is ignored in production to prevent spoofing.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Production API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox Environment
security:
  - APIKey: []
tags:
  - name: Authentication
    description: API key and token management
  - name: Issuers
    description: Issuer registration and trust management
  - name: Keys
    description: Cryptographic key management for issuers
  - name: Attestations
    description: Attestation lifecycle (mint, revoke, supersede)
  - name: Verification
    description: Attestation verification and proof bundles
  - name: Governance
    description: Issuer governance workflows (admin only)
  - name: Identity
    description: Organization, user, and role management
  - name: Audit
    description: Audit event queries
  - name: Platform
    description: Platform administration (super admin only)
  - name: Platform Review
    description: Staff review workflows for issuer applications
  - name: Tenant Console
    description: Tenant profile and lifecycle endpoints
  - name: Health
    description: Service health and readiness endpoints
  - name: Risk
    description: Risk signal ingestion and fraud detection
  - name: Risk Enforcement
    description: Risk enforcement actions — block, challenge, quarantine, and configuration
  - name: Billing
    description: Billing, subscription, and addon management
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
      trust, witness, compliance, orchestration, and observability
externalDocs:
  description: Transparency read-only API (separate service spec)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/attestations/{id}/supersede:
    post:
      tags:
        - Attestations
      summary: Supersede Attestation
      description: |
        Creates a new attestation that supersedes an existing one.
        The original attestation is marked as SUPERSEDED.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - payload
              properties:
                payload:
                  type: object
                  description: Updated payload for the new attestation
            example:
              payload:
                subject: user:12345
                claim: verified_email
                value: newemail@example.com
      responses:
        '201':
          description: New attestation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attestation'
      security:
        - APIKey: []
components:
  schemas:
    Attestation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        issuer_id:
          type: string
          format: uuid
        kid:
          type: string
        status:
          type: string
          enum:
            - VALID
            - REVOKED
            - SUPERSEDED
        payload:
          type: object
        signature:
          type: string
        log_index:
          type: integer
        created_at:
          type: string
          format: date-time
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication

````