openapi: 3.2.0
info:
  title: Oxide Region System/audit Log API
  description: API for interacting with the Oxide control plane
  contact:
    url: https://oxide.computer
    email: api@oxide.computer
  version: 2026081901.0.0
tags:
- name: system/audit-log
  description: These endpoints relate to audit logs.
  externalDocs:
    url: http://docs.oxide.computer/api/system-audit-log
paths:
  /v1/system/audit-log:
    get:
      tags:
      - system/audit-log
      summary: View audit log
      description: 'A single item in the audit log represents both the beginning and end of the logged operation (represented by `time_started` and `time_completed`) so that clients do not have to find multiple entries and match them up by request ID to get the full picture of an operation. Because timestamps may not be unique, entries have also have a unique `id` that can be used to deduplicate items fetched from overlapping time intervals.


        Audit log entries are designed to be immutable: once you see an entry, fetching it again will never get you a different result. The list is ordered by `time_completed`, not `time_started`. If you fetch the audit log for a time range that is fully in the past, the resulting list is guaranteed to be complete, i.e., fetching the same timespan again later will always produce the same set of entries.'
      operationId: audit_log_list
      parameters:
      - in: query
        name: end_time
        description: Exclusive
        schema:
          type:
          - string
          - 'null'
          format: date-time
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: sort_by
        schema:
          $ref: '#/components/schemas/TimeAndIdSortMode'
      - in: query
        name: start_time
        description: Required, inclusive
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogEntryResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required:
        - start_time
components:
  schemas:
    AuditLogEntryResult:
      description: Result of an audit log entry
      oneOf:
      - description: The operation completed successfully
        type: object
        properties:
          http_status_code:
            description: HTTP status code
            type: integer
            format: uint16
            minimum: 0
          kind:
            type: string
            enum:
            - success
        required:
        - http_status_code
        - kind
      - description: The operation failed
        type: object
        properties:
          error_code:
            type:
            - string
            - 'null'
          error_message:
            type: string
          http_status_code:
            description: HTTP status code
            type: integer
            format: uint16
            minimum: 0
          kind:
            type: string
            enum:
            - error
        required:
        - error_message
        - http_status_code
        - kind
      - description: After the logged operation completed, our attempt to write the result to the audit log failed, so it was automatically marked completed later by a background job. This does not imply that the operation itself timed out or failed, only our attempts to log its result.
        type: object
        properties:
          kind:
            type: string
            enum:
            - unknown
        required:
        - kind
    TimeAndIdSortMode:
      description: Supported set of sort modes for scanning by timestamp and ID
      oneOf:
      - description: Sort in increasing order of timestamp and ID, i.e., earliest first
        type: string
        enum:
        - time_and_id_ascending
      - description: Sort in increasing order of timestamp and ID, i.e., most recent first
        type: string
        enum:
        - time_and_id_descending
    AuditLogEntryResultsPage:
      description: A single page of results
      type: object
      properties:
        items:
          description: list of items on this page of results
          type: array
          items:
            $ref: '#/components/schemas/AuditLogEntry'
        next_page:
          description: token used to fetch the next page of results (if any)
          type:
          - string
          - 'null'
      required:
      - items
    AuthMethod:
      description: Authentication method used for a request
      oneOf:
      - description: Console session cookie
        type: string
        enum:
        - session_cookie
      - description: Device access token (OAuth 2.0 device authorization flow)
        type: string
        enum:
        - access_token
      - description: SCIM client bearer token
        type: string
        enum:
        - scim_token
    AuditLogEntryActor:
      oneOf:
      - type: object
        properties:
          kind:
            type: string
            enum:
            - user_builtin
          user_builtin_id:
            type: string
            format: uuid
        required:
        - kind
        - user_builtin_id
      - type: object
        properties:
          kind:
            type: string
            enum:
            - silo_user
          silo_id:
            type: string
            format: uuid
          silo_user_id:
            type: string
            format: uuid
        required:
        - kind
        - silo_id
        - silo_user_id
      - type: object
        properties:
          kind:
            type: string
            enum:
            - scim
          silo_id:
            type: string
            format: uuid
        required:
        - kind
        - silo_id
      - type: object
        properties:
          kind:
            type: string
            enum:
            - unauthenticated
        required:
        - kind
    Error:
      description: Error information from a response.
      type: object
      properties:
        error_code:
          type: string
        message:
          type: string
        request_id:
          type: string
      required:
      - message
      - request_id
    AuditLogEntry:
      description: Audit log entry
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/AuditLogEntryActor'
        auth_method:
          description: How the user authenticated the request (access token, session, or SCIM token). Null for unauthenticated requests like login attempts.
          allOf:
          - $ref: '#/components/schemas/AuthMethod'
        credential_id:
          description: ID of the credential used for authentication. Null for unauthenticated requests. The value of `auth_method` indicates what kind of credential it is (access token, session, or SCIM token).
          type:
          - string
          - 'null'
          format: uuid
        id:
          description: Unique identifier for the audit log entry
          type: string
          format: uuid
        operation_id:
          description: API endpoint ID, e.g., `project_create`
          type: string
        request_id:
          description: Request ID for tracing requests through the system
          type: string
        request_uri:
          description: URI of the request, truncated to 512 characters. Will only include host and scheme for HTTP/2 requests. For HTTP/1.1, the URI will consist of only the path and query.
          type: string
        result:
          description: Result of the operation
          allOf:
          - $ref: '#/components/schemas/AuditLogEntryResult'
        source_ip:
          description: IP address that made the request
          type: string
          format: ip
        time_completed:
          description: Time operation completed
          type: string
          format: date-time
        time_started:
          description: When the request was received
          type: string
          format: date-time
        user_agent:
          description: User agent string from the request, truncated to 256 characters.
          type:
          - string
          - 'null'
      required:
      - actor
      - id
      - operation_id
      - request_id
      - request_uri
      - result
      - source_ip
      - time_completed
      - time_started
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'