# Proposed contract, version 1: endpoints, errors, paging, idempotency, security and the capability of every
# operation. Resource schemas were initialized from the data model (docs/06-data) and are kept aligned with it; input
# schemas (*Input, *Request) and views are specific to this contract. Status: proposal for review, not confirmed design.
# Conventions: docs/05-interfaces/choosing-an-interface.md. Vendor extensions: x-moonitoring-audience (who calls),
# x-moonitoring-capability (the capability checked), x-moonitoring-entitlement (the entitlement feature checked),
# x-moonitoring-requirements (the requirements of 1.requisiti-raffinati.txt the operation serves).
openapi: 3.1.0
info:
  title: Access Audit API
  version: 1.0.0
  description: 'The record of every privileged action taken in the Console or through an admin API of any system:
    who did what, when, with which capability. Systems write the row in the same transaction as the change and publish
    it; `access` consolidates the rows and serves them here.'
servers:
- url: https://access.moonitoring.com/audit/v1
  description: Prod
- url: https://stage-access.moonitoring.com/audit/v1
  description: Stage, through IAP
security:
- bearer: []
tags:
- name: Events
  description: Platform audit events
paths:
  /events:
    get:
      summary: List audit events
      operationId: listAuditEvents
      description: Newest first, by occurred_at.
      tags:
      - Events
      parameters:
      - name: actor
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Only actions of this Moonitoring user.
      - name: organization
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Only actions on this Organization, the subject (decided 2026-11-11).
      - name: acting_organization
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Only actions of users acting as this Organization, the token's active Organization, such as an
          insurer acting on the farms that delegated to it (decided 2026-11-11).
      - name: action
        in: query
        required: false
        schema:
          type: string
        description: Only this action, e.g. releases.releases.approve.
      - name: target_type
        in: query
        required: false
        schema:
          type: string
        description: Only this entity name, e.g. AgentModelProfile.
      - name: target_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Only this target.
      - name: system
        in: query
        required: false
        schema:
          type: string
        description: Only actions recorded by this system.
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Occurred at or after.
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Occurred before.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformAuditEvent'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      x-moonitoring-audience: staff
      x-moonitoring-capability: access.audit.read
      x-moonitoring-requirements:
      - '70'
      - '70.13'
      - '70.15'
      - '1006.28'
  /events/{event_id}:
    get:
      summary: Read an audit event
      operationId: getAuditEvent
      tags:
      - Events
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformAuditEvent'
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      x-moonitoring-audience: staff
      x-moonitoring-capability: access.audit.read
      x-moonitoring-requirements:
      - '70'
      - '1006.28'
  /organizations/{organization_id}/events:
    get:
      summary: List the audit events of my Organization
      operationId: listOrganizationAuditEvents
      description: 'Proposed on 2026-11-10 with the predefined roles. The audit of one Organization for its own
        owners (req 70.13): the rows whose organization is this one, newest first, including the actions staff took
        on it; whether staff are shown by name is not decided yet.'
      tags:
      - Events
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The Organization.
      - name: action
        in: query
        required: false
        schema:
          type: string
        description: Only this action, e.g. access.members.revoke.
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Occurred at or after.
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Occurred before.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformAuditEvent'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      x-moonitoring-audience: organization
      x-moonitoring-capability: access.organization_audit.read
      x-moonitoring-capability-status: proposed
      x-moonitoring-requirements:
      - '70.13'
components:
  schemas:
    PlatformAuditEvent:
      description: 'Who did what, and when, in the Console, through every admin API and in the administration of an Organization: one immutable row per important
        action, written in the same transaction as the change it records, with the capability that allowed it and
        the fields that changed. Rows are copied to the locked audit log bucket, so the person who acted can never
        alter the record of it. Immutable.'
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        actor:
          type: string
          format: uuid
          description: ID of the MoonitoringUser who acted; exactly one of actor and user is set.
        user:
          type: string
          format: uuid
          description: ID of the User (an Organization user or ServiceAccount) who acted.
        organization:
          type: string
          format: uuid
          description: ID of the Organization the action concerns, when it concerns one; through a delegation, the
            subject, the farm acted on.
        acting_organization:
          type: string
          format: uuid
          description: 'ID of the Organization the user acted as, the token''s active Organization (decided
            2026-11-11). It differs from organization when they acted through a delegation: "Mario Rossi, for
            Assicurazioni X, on Cascina Uno". Absent for staff and for a system acting on its own.'
        action:
          type: string
          description: Named like a capability, <system>.<resource>.<verb>, e.g. `moochat.agent_models.update`,
            `releases.releases.approve`.
        capability:
          type: string
          description: The capability that allowed the action, as checked at that moment; absent when the action
            needed none, as a join through a link.
        target_type:
          type: string
          description: The entity name, e.g. AgentModelProfile.
        target_id:
          type: string
          format: uuid
        before:
          type: string
        after:
          type: string
          description: The changed fields only; secrets and prompts are never copied here.
        system:
          type: string
          description: The system that made the change and wrote the row, e.g. moochat.
        request_id:
          type: string
          description: The same id as in Cloud Logging, so the technical log and the audit row meet.
        occurred_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
      - id
      - action
      - target_type
      - target_id
      - request_id
      - occurred_at
      - created_at
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The short-lived token signed by `access`: an Organization user token, a staff token or a client
        token, as the operation''s audience says.'