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

# Read the calling organization's slice of the audit log

> Returns identity registration, credential issuance, and revocation events, scoped to a `principal_ref`, `business_ref`, or `jti` your organization already holds — at least one is required. Reads the sequenced log, which the batch sequencer populates asynchronously, so very recent events may lag slightly behind the fast-store freshness path.



## OpenAPI

````yaml /api-reference/openapi.json get /audit-log
openapi: 3.1.0
info:
  title: baselayer-api-service
  version: 0.1.0
servers:
  - url: https://api.baselayer.com/
security: []
paths:
  /audit-log:
    get:
      tags:
        - Audit Log
      summary: Read the calling organization's slice of the audit log
      description: >-
        Returns identity registration, credential issuance, and revocation
        events, scoped to a `principal_ref`, `business_ref`, or `jti` your
        organization already holds — at least one is required. Reads the
        sequenced log, which the batch sequencer populates asynchronously, so
        very recent events may lag slightly behind the fast-store freshness
        path.
      operationId: list_audit_log_entries
      parameters:
        - name: principal_ref
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Principal Ref
        - name: business_ref
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Business Ref
        - name: jti
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Jti
        - name: event_type
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/AuditEventType'
              - type: 'null'
            title: Event Type
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            description: >-
              Maximum number of records to return in a single page. Must be
              between 1 and 1000.
            default: 10
            title: Limit
          description: >-
            Maximum number of records to return in a single page. Must be
            between 1 and 1000.
        - name: offset
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            description: >-
              Number of records to skip from the beginning. Use 0 for the first
              page. Cannot be used with cursor.
            title: Offset
          description: >-
            Number of records to skip from the beginning. Use 0 for the first
            page. Cannot be used with cursor.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Opaque pagination cursor token that identifies the position in the
              result set. Use the cursor from the previous response to get the
              next page. Cannot be used with offset.
            title: Cursor
          description: >-
            Opaque pagination cursor token that identifies the position in the
            result set. Use the cursor from the previous response to get the
            next page. Cannot be used with offset.
      responses:
        '200':
          description: List of audit-log entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/v1.AuditLogEntryResponse'
            application/vnd.baselayer.v1+json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/v1.AuditLogEntryResponse'
          headers:
            X-Total-Count:
              description: Total number of records matching the query.
              schema:
                type: integer
            X-Total-Pages:
              description: Total number of pages available based on the current limit.
              schema:
                type: integer
            X-Next-Cursor:
              description: >-
                Cursor for the next page (only present when using the keyset
                pagination and if `has_more` is true.
              schema:
                type: string
        '404':
          description: >-
            The principal_ref, business_ref, or jti is unknown or belongs to
            another organization — the two are indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
                title: ResourceNotFound
                description: Could not locate the resource for the given URI.
                examples:
                  - code: 1
                    message: Could not locate the resource for the given URI.
                    metadata: {}
        '422':
          description: >-
            No scoping filter was provided, or event_type named an event type
            this route doesn't expose.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
                title: InvalidAuditLogQuery
                description: >-
                  The audit-log query requires at least one of principal_ref,
                  business_ref, or jti to scope the read to your organization's
                  own refs, and event_type (when given) must be one this route
                  exposes.
                examples:
                  - code: 6310
                    message: >-
                      The audit-log query requires at least one of
                      principal_ref, business_ref, or jti to scope the read to
                      your organization's own refs, and event_type (when given)
                      must be one this route exposes.
                    metadata: {}
      security:
        - APIKeyHeader: []
components:
  schemas:
    AuditEventType:
      type: string
      enum:
        - issuance
        - consumption
        - identity_registration
        - counterparty_registration
        - credential_revocation
        - credential_mint_failed
      title: AuditEventType
      description: >-
        The kinds of event recorded in the tamper-evident audit log.


        ``Consumption`` dominates by volume — it fires on every agent request to

        every merchant.


        This diverges deliberately from the original brief's "five event types".

        Consent was dropped (it went unused), and the two categories that the
        brief

        treated as single types each carry genuinely different payloads, so they
        are

        split rather than discriminated inside one type:


        * registration — a counterparty publishing its disclosure profile is
          unrelated to a person completing identity verification;
        * revocation — one short-lived credential killed by ``jti``. Nothing
          withdraws a subject's authority to mint, so this is the only shape.

        Because ``event_type`` is a VARCHAR column rather than a native Postgres

        enum, adding or renaming a member here needs no migration.
    v1.AuditLogEntryResponse:
      description: |-
        One committed audit-log entry, sliced to the caller's own org-scoped
        refs (``GET /audit-log``).
      properties:
        seq:
          description: The entry's permanent sequence number (Merkle leaf index).
          title: Seq
          type: integer
        event:
          description: The decoded audit event.
          discriminator:
            mapping:
              credential_revocation:
                $ref: '#/components/schemas/v1.CredentialRevocationEvent'
              identity_registration:
                $ref: '#/components/schemas/v1.IdentityRegistrationEvent'
              issuance:
                $ref: '#/components/schemas/v1.IssuanceEvent'
            propertyName: event_type
          oneOf:
            - $ref: '#/components/schemas/v1.IssuanceEvent'
            - $ref: '#/components/schemas/v1.CredentialRevocationEvent'
            - $ref: '#/components/schemas/v1.IdentityRegistrationEvent'
          title: Event
      required:
        - seq
        - event
      title: AuditLogEntryResponse (v1)
      type: object
    APIError:
      properties:
        code:
          type: integer
          title: Code
        message:
          type: string
          title: Message
        uri:
          anyOf:
            - type: string
            - type: 'null'
          title: Uri
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
        - code
        - message
      title: APIError
      description: >-
        APIError is a Pydantic model for standardizing error responses from the
        API.


        This class is used internally by APIException for JSON serialization.

        Users should typically work with APIException directly in exception
        catalogs.
    v1.CredentialRevocationEvent:
      additionalProperties: false
      description: |-
        One credential killed by ``jti``.

        The subject keeps its authority to mint, so this event says one artifact
        died and nothing about what may be issued next.
      properties:
        schema_version:
          default: 1
          minimum: 1
          title: Schema Version
          type: integer
        occurred_at:
          format: date-time
          title: Occurred At
          type: string
        event_type:
          const: credential_revocation
          title: Event Type
          type: string
        jti:
          maxLength: 255
          minLength: 1
          title: Jti
          type: string
        principal_ref:
          anyOf:
            - maxLength: 128
              minLength: 4
              type: string
            - type: 'null'
          default: null
          title: Principal Ref
        business_ref:
          anyOf:
            - maxLength: 128
              minLength: 4
              type: string
            - type: 'null'
          default: null
          title: Business Ref
        audience:
          anyOf:
            - maxLength: 253
              minLength: 1
              type: string
            - type: 'null'
          default: null
          title: Audience
        reason:
          $ref: '#/components/schemas/v1.AuditRevocationReason'
        effective_at:
          format: date-time
          title: Effective At
          type: string
      required:
        - occurred_at
        - jti
        - reason
        - effective_at
        - event_type
      title: CredentialRevocationEvent
      type: object
    v1.IdentityRegistrationEvent:
      additionalProperties: false
      description: |-
        An identity submission or hosted session yielding a ``principal_ref``.

        The birth record of a principal in this log. Both origination paths
        (direct submission and hosted embed) converge on the same refs, so one
        shape covers both.
      properties:
        schema_version:
          default: 1
          minimum: 1
          title: Schema Version
          type: integer
        occurred_at:
          format: date-time
          title: Occurred At
          type: string
        event_type:
          const: identity_registration
          title: Event Type
          type: string
        principal_ref:
          maxLength: 128
          minLength: 4
          title: Principal Ref
          type: string
        business_ref:
          anyOf:
            - maxLength: 128
              minLength: 4
              type: string
            - type: 'null'
          default: null
          title: Business Ref
        submission_id:
          maxLength: 255
          minLength: 1
          title: Submission Id
          type: string
        verdict:
          $ref: '#/components/schemas/v1.OnboardingVerdict'
        active_keys:
          default: []
          items:
            type: string
          title: Active Keys
          type: array
        verification_level:
          anyOf:
            - maximum: 4
              minimum: 0
              type: integer
            - type: 'null'
          default: null
          title: Verification Level
        business_operator_link_status:
          anyOf:
            - $ref: '#/components/schemas/v1.BusinessOperatorLinkStatus'
            - type: 'null'
          default: null
      required:
        - occurred_at
        - principal_ref
        - submission_id
        - verdict
        - event_type
      title: IdentityRegistrationEvent
      type: object
    v1.IssuanceEvent:
      additionalProperties: false
      description: >-
        A credential mint.


        Mirrors the mint response (``osiris.schemas.v1.credential``) minus the

        credential string itself, which is a short-TTL projection we
        deliberately

        never store.
      properties:
        schema_version:
          default: 1
          minimum: 1
          title: Schema Version
          type: integer
        occurred_at:
          format: date-time
          title: Occurred At
          type: string
        event_type:
          const: issuance
          title: Event Type
          type: string
        jti:
          maxLength: 255
          minLength: 1
          title: Jti
          type: string
        credential_type:
          $ref: '#/components/schemas/v1.IssuedCredentialType'
        principal_ref:
          anyOf:
            - maxLength: 128
              minLength: 4
              type: string
            - type: 'null'
          default: null
          title: Principal Ref
        business_ref:
          anyOf:
            - maxLength: 128
              minLength: 4
              type: string
            - type: 'null'
          default: null
          title: Business Ref
        audience:
          maxLength: 253
          minLength: 1
          title: Audience
          type: string
        issued_at:
          format: date-time
          title: Issued At
          type: string
        expires_at:
          format: date-time
          title: Expires At
          type: string
        disclosed_fields:
          default: []
          items:
            maxLength: 128
            pattern: ^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$
            type: string
          maxItems: 256
          title: Disclosed Fields
          type: array
        disclosure_mode:
          anyOf:
            - $ref: '#/components/schemas/v1.DisclosureMode'
            - type: 'null'
          default: null
        active_keys:
          default: []
          items:
            type: string
          title: Active Keys
          type: array
        signing_kid:
          maxLength: 255
          minLength: 1
          title: Signing Kid
          type: string
        agent_key_thumbprint:
          anyOf:
            - maxLength: 255
              type: string
            - type: 'null'
          default: null
          title: Agent Key Thumbprint
      required:
        - occurred_at
        - jti
        - credential_type
        - audience
        - issued_at
        - expires_at
        - signing_kid
        - event_type
      title: IssuanceEvent
      type: object
    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.OnboardingVerdict:
      description: Normalized onboarding verdict used across provider-specific outputs.
      enum:
        - APPROVED
        - UNDER_REVIEW
        - REJECTED
      title: OnboardingVerdict
      type: string
    v1.BusinessOperatorLinkStatus:
      description: |-
        Status of the link between a person (principal) and a business they
        operate.

        VERIFIED is earned by the full evidence recipe (TIN provided +
        IRS-matched + KYB-verified) or granted by manual review; UNDER_REVIEW
        is every automatic shortfall; REJECTED is a manual refusal. A rejected
        link is immutable — a later submission evaluates the pair fresh.
      enum:
        - VERIFIED
        - UNDER_REVIEW
        - REJECTED
      title: BusinessOperatorLinkStatus
      type: string
    v1.IssuedCredentialType:
      description: |-
        The KYA credential layer.

        L2 is the audience-scoped pairwise DID ("same customer returning");
        L3 is the selectively disclosed verified-identity credential. Both ride
        the same SD-JWT-VC wire format; the layer decides what the issuer JWT
        carries. Counterparty is the counterparty-verification credential
        (ENG-6598): a domain-bound business entity attestation a merchant
        hosts for arriving agents — plain JWS, no selective disclosure, no
        agent key.
      enum:
        - L2
        - L3
        - COUNTERPARTY
      title: IssuedCredentialType
      type: string
    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
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````