> ## Documentation Index > Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt > Use this file to discover all available pages before exploring further. # Revoke one credential > Flips this credential's bit in the unified Token Status List, so verifiers refuse it from their next list fetch — for a leaked presentation or any single artifact that has to stop working before it expires. The revocation is scoped to this one credential: the subject keeps its authorization, so a replacement is a fresh mint away. Nothing is deleted — the record is evidence and stays readable at `GET /issuance/credentials/{credential_id}` with `status: REVOKED`; this action answers with that record. The reason and the revoking user or API key are recorded on the record and its audit event. Idempotent: revoking an already-revoked credential changes nothing, keeps the first reason and revoker, and returns the same record. ## OpenAPI ````yaml /api-reference/openapi.json post /issuance/credentials/{credential_id}/revoke openapi: 3.1.0 info: title: baselayer-api-service version: 0.1.0 servers: - url: https://api.baselayer.com/ security: [] paths: /issuance/credentials/{credential_id}/revoke: post: tags: - Credentials summary: Revoke one credential description: >- Flips this credential's bit in the unified Token Status List, so verifiers refuse it from their next list fetch — for a leaked presentation or any single artifact that has to stop working before it expires. The revocation is scoped to this one credential: the subject keeps its authorization, so a replacement is a fresh mint away. Nothing is deleted — the record is evidence and stays readable at `GET /issuance/credentials/{credential_id}` with `status: REVOKED`; this action answers with that record. The reason and the revoking user or API key are recorded on the record and its audit event. Idempotent: revoking an already-revoked credential changes nothing, keeps the first reason and revoker, and returns the same record. operationId: issuance_credentials_revoke parameters: - name: credential_id in: path required: true schema: type: string description: >- The credential's unique id: the `jti` its token carries, as returned by the mint. title: Credential Id description: >- The credential's unique id: the `jti` its token carries, as returned by the mint. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/v1.RevokeCredentialRequest' application/vnd.baselayer.v1+json: schema: $ref: '#/components/schemas/v1.RevokeCredentialRequest' responses: '200': description: Response content: application/json: schema: $ref: '#/components/schemas/v1.IssuedCredentialResponse' application/vnd.baselayer.v1+json: schema: $ref: '#/components/schemas/v1.IssuedCredentialResponse' '404': description: >- The id is unknown or names another organization's credential — the two are indistinguishable. content: application/json: schema: $ref: '#/components/schemas/Error' title: ResourceNotFound description: Could not locate the resource for the given URI. examples: - type: resource_not_found code: 1 message: Could not locate the resource for the given URI. metadata: {} '422': description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Error' title: ValidationFailed description: The request is invalid. examples: - type: validation_failed code: 7112 message: The request is invalid. metadata: {} security: - APIKeyHeader: [] components: schemas: v1.RevokeCredentialRequest: additionalProperties: false description: Why a credential is being revoked. properties: reason: $ref: '#/components/schemas/v1.CustomerRevocationReason' description: >- Why the credential is being revoked; recorded on the issuance record and its audit event. required: - reason title: RevokeCredentialRequest (v1) type: object v1.IssuedCredentialResponse: description: |- One record from the organization's credential issuance log. The dispute-evidence view of a mint: who was authorized, for which counterparty, disclosing what, signed with which key, and whether the credential has since been revoked, keyed by the ``credential_id`` (the token's ``jti``) a relying party's exchange log records. Carries no credential material; only ``IssuedCredentialDetailResponse`` does. properties: credential_id: description: 'The credential''s unique id: exactly the `jti` its token carries.' title: Credential Id type: string environment: $ref: '#/components/schemas/v1.ApplicationType' description: The environment the credential was minted in. source_environment: anyOf: - $ref: '#/components/schemas/v1.ApplicationType' - type: 'null' default: null description: >- On a test credential for a person or business verified in another environment, that environment; the credential itself is signed in `environment`. Null otherwise. level: $ref: '#/components/schemas/v1.CredentialMintLevel' description: The credential layer minted. credential_format: $ref: '#/components/schemas/v1.CredentialWireFormat' description: The credential's wire format. iss: description: 'The token''s `iss` claim: the issuer that signed it.' title: Iss type: string vct: description: 'The token''s `vct` claim: the credential type identifier.' title: Vct type: string status_list: $ref: '#/components/schemas/v1.CredentialStatusListPointer' description: >- The token's `status.status_list` claim: where a verifier reads this credential's revocation bit. linked_credential_id: anyOf: - type: string - type: 'null' default: null description: >- On a business L3 mint's actor credential, the `credential_id` of the business credential minted with it; null otherwise. title: Linked Credential Id status: $ref: '#/components/schemas/v1.IssuedCredentialStatus' description: >- The credential's persisted revocation standing: `VALID`, or `REVOKED` once its bit is set on the published status list. Expiry does not change it. state: $ref: '#/components/schemas/v1.IssuedCredentialLifecycleState' description: >- The credential's lifecycle as of this request: `ACTIVE`, `EXPIRED` once `expires_at` has passed, or `REVOKED`. The same value the `state` filter selects on. revoked_at: anyOf: - format: date-time type: string - type: 'null' default: null description: The instant the credential was revoked; null while it remains valid. title: Revoked At revocation_reason: anyOf: - $ref: '#/components/schemas/v1.AuditRevocationReason' - type: 'null' default: null description: >- Why the credential was revoked. Null while it remains valid and on records revoked before the reason was recorded. revoked_by: anyOf: - $ref: '#/components/schemas/v1.ActedBy' - type: 'null' default: null description: >- Who revoked the credential: the console user or the API key. Captured at revocation and never rewritten. Null while the credential remains valid and on records revoked before the actor was recorded. individual_ref: anyOf: - type: string - type: 'null' default: null description: >- The pairwise individual reference involved in the mint: the individual subject, or the acting individual who authorized a business mint. Null on counterparty mints and when that individual no longer exists. title: Individual Ref individual_display_name: anyOf: - type: string - type: 'null' default: null description: >- The first and last name of the individual `individual_ref` names, as the credential minted it. Null on counterparty mints and on records minted before names were recorded. title: Individual Display Name business_ref: anyOf: - type: string - type: 'null' default: null description: >- The pairwise business reference minted for, as issued to your organization; null on individual mints and when the subject no longer exists. title: Business Ref business_legal_name: anyOf: - type: string - type: 'null' default: null description: >- The business's legal name as the credential minted it. Null on individual mints and on records minted before names were recorded. title: Business Legal Name audience: description: The canonical audience the credential is scoped to. title: Audience type: string subject: anyOf: - type: string - type: 'null' default: null description: >- Counterparty credentials only: the public business DID the credential's sub claim carries; null on agent credentials. title: Subject issued_at: description: Issuance instant (the issuer JWT's iat). format: date-time title: Issued At type: string expires_at: description: Expiry instant (the issuer JWT's exp). format: date-time title: Expires At type: string disclosed_fields: description: >- The dotted disclosure paths the credential carries; empty for L2 mints. items: type: string title: Disclosed Fields type: array active_keys: description: >- Names of the verification checks that passed (e.g. `phone_possession` for an individual, `tax_id_match` for a business), from the token-exchange profile's key vocabulary; the verification level is derived from them. items: type: string title: Active Keys type: array signing_kid: description: >- The id of the issuer key that signed the credential (the RFC 7638 thumbprint published in the issuer's JWKS). title: Signing Kid type: string minted_by: anyOf: - $ref: '#/components/schemas/v1.ActedBy' - type: 'null' default: null description: >- Who initiated the mint: the console user or the API key. Captured at mint time and never rewritten. Null on records minted before the actor's kind was recorded. agent_key_kid: anyOf: - type: string - type: 'null' default: null description: >- The caller-supplied kid of the agent key the credential was bound to, if one was provided. Null on counterparty credentials and on records minted before it was recorded. title: Agent Key Kid agent_key_thumbprint: anyOf: - type: string - type: 'null' default: null description: >- RFC 7638 thumbprint of the agent public key bound into the credential's cnf claim. Null on counterparty credentials and on records minted before it was recorded. title: Agent Key Thumbprint disclosure_mode: anyOf: - $ref: '#/components/schemas/v1.DisclosureMode' - type: 'null' default: null description: >- The selective-disclosure mode the mint requested. Null on L2 and counterparty mints, and on L3 records minted before it was recorded. preset: anyOf: - maxLength: 32 pattern: ^[a-z][a-z0-9_]*$ type: string - type: 'null' default: null description: >- The preset the mint disclosed by; null when it listed its own disclosed_fields, and on L2 and counterparty mints. title: Preset required: - credential_id - environment - level - credential_format - iss - vct - status_list - status - state - audience - issued_at - expires_at - signing_kid title: IssuedCredentialResponse (v1) type: object Error: properties: type: type: string title: Type description: >- Stable snake_case name of the error. Branch on this, never on `message`. code: type: integer title: Code description: Integer catalog code of the error. message: type: string title: Message description: For a human reading a log; not stable and not localized. metadata: additionalProperties: true type: object title: Metadata description: Context documented per `type`. request_id: anyOf: - type: string - type: 'null' title: Request Id description: The `X-Request-ID` of the failed request. type: object required: - type - code - message title: Error description: The one body of every error a KYA route answers. v1.CustomerRevocationReason: description: |- Why a customer revoked a credential by hand: ``AuditRevocationReason`` without ``administrative_action``, which stays Baselayer's. enum: - agent_key_compromise - identity_superseded - identity_withdrawn - operator_link_revoked - fraud_suspected title: CustomerRevocationReason type: string v1.ApplicationType: enum: - sandbox - production title: ApplicationType type: string v1.CredentialMintLevel: description: |- The credential layer a subject mint request selects (KYA). Deliberately narrower than ``IssuedCredentialType``: the individual and business mint routes issue only the two subject layers. Counterparty credentials have their own route and request shape, so a ``level`` of COUNTERPARTY must stay an edge-level payload refusal — this enum is what keeps issuance-record vocabulary growth from widening the mint requests. enum: - L2 - L3 title: CredentialMintLevel type: string v1.CredentialWireFormat: description: |- The credential formats issued. The value is the SD-JWT VC media-type subtype, a standard code kept verbatim. Validation accepts the stored ``SD_JWT_VC`` member, never that string. enum: - dc+sd-jwt title: CredentialWireFormat type: string v1.CredentialStatusListPointer: description: A credential's reference into a published Token Status List. properties: uri: description: The status list's URI. title: Uri type: string idx: description: The credential's index on that list. title: Idx type: integer required: - uri - idx title: CredentialStatusListPointer (v1) type: object v1.IssuedCredentialStatus: description: |- The credential's state on the published Token Status List. Valid is the mint-time state; Revoked is terminal: the organization or an individual pulling this one credential, or our own compromise response. Expiry is deliberately not a status: verifiers already check ``exp``, and the bit must keep meaning "revoked before expiry" for the issuance log. enum: - VALID - REVOKED title: IssuedCredentialStatus type: string v1.IssuedCredentialLifecycleState: description: |- A credential's effective state as an issuance-log reader sees it. Derived, never stored: ``IssuedCredentialStatus`` deliberately keeps expiry out of the persisted status (verifiers check ``exp``), but the console and API consumers filter the log by what a credential *is* right now — still presentable, aged out, or killed. enum: - ACTIVE - EXPIRED - REVOKED title: IssuedCredentialLifecycleState type: string v1.AuditRevocationReason: description: >- Why a credential was revoked. The reason is the part of a revocation record a dispute actually reads, so the vocabulary has to distinguish the paths that reach it. enum: - agent_key_compromise - identity_superseded - identity_withdrawn - operator_link_revoked - fraud_suspected - administrative_action title: AuditRevocationReason type: string v1.ActedBy: description: |- Who acted on a record, as they were named when they acted: the one actor shape every route answers. properties: kind: $ref: '#/components/schemas/v1.ActedByKind' description: '`USER` for a console user, `API_KEY` for a key.' label: description: >- The user's first and last name or the API key's name, as they were when they acted; never rewritten by a later rename or deletion. title: Label type: string required: - kind - label title: ActedBy (v1) type: object v1.DisclosureMode: description: |- Per-mint selective-disclosure mode for L3 credentials. CLEARTEXT_AND_HASH (the default) discloses requested fields as cleartext alongside their recognition hashes; HASH_ONLY discloses only the recognition hashes, giving counterparties recognition without plaintext. Lives here rather than beside the L3 payload shapes because it is a stored column vocabulary as of ENG-7140 (``issued_credentials.disclosure_mode``), and ``models.py`` cannot import ``osiris.identity.l3_payloads`` (circular through ``active_keys``). enum: - CLEARTEXT_AND_HASH - HASH_ONLY title: DisclosureMode type: string v1.ActedByKind: description: 'Who acted on a record: a console user or an API key.' enum: - USER - API_KEY title: ActedByKind type: string securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.