openapi: 3.0.1
info:
  title: Events API
  description: 1Password Events API Specification.
  version: 3.0.0
servers:
  - url: https://events.1password.com
    description: 1Password
  - url: https://events.1password.ca
    description: 1Password CA
  - url: https://events.1password.eu
    description: 1Password EU
  - url: https://events.ent.1password.com
    description: 1Password Enterprise
tags:
  - name: api-v3
paths:
  /api/v3/auditevents:
    get:
      summary: Retrieves audit events for actions performed by team members within a 1Password account
      tags:
        - api-v3
      operationId: getAuditEvents
      security:
        - Jwt-saBearerAuth: []
      parameters:
        - in: query
          name: page_size
          description: The maximum number of results to return in a single request.
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 1000
        - in: query
          name: next_page_token
          description: An opaque token identifying the next page of results to retrieve.
          schema:
            type: string
        - in: query
          name: start_time
          description: The earliest timestamp for which to retrieve results (inclusive). Invalid if next_page_token is specified.
          schema:
            type: string
            format: date-time
        - in: query
          name: end_time
          description: The latest timestamp for which to retrieve results (inclusive). Invalid if next_page_token is specified.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          $ref: "#/components/responses/AuditEventsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "400":
          $ref: "#/components/responses/BadRequestResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
components:
  securitySchemes:
    Jwt-saBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Account:
      type: object
      description: An account associated with a given event.
      example:
        uuid: "56YE2TYN2VFYRLNSHKPW5NVT5E"
        name: "Some Account Name"
        state: "A"
        type: "B"
        domain: "domain.com"
      required:
        - uuid
        - name
        - state
        - type
        - domain
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        name:
          type: string
          example: "Some Account Name"
        state:
          type: string
          example: "A"
        type:
          type: string
          example: "B"
        domain:
          type: string
          example: "domain.com"
    Actor:
      type: object
      description: The initiator of the action which produced a given event.
      example:
        type: "user"
        uuid: "56YE2TYN2VFYRLNSHKPW5NVT5E"
        name: "Some User"
        email: "user.email@domain.com"
        linked_account:
          uuid: "3JPKX6XC6BDDBJGJYCLOSVXQE4"
          name: "Some Account Name"
      required:
        - type
        - uuid
      properties:
        type:
          type: string
        uuid:
          $ref: "#/components/schemas/UUID"
        name:
          type: string
        email:
          type: string
          format: email
        linked_account:
          $ref: "#/components/schemas/Account"
    AuditEvent:
      type: object
      required:
        - uuid
        - timestamp
        - context
        - actor
        - category
        - action
        - targets
      description: A single audit event object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        timestamp:
          type: string
          format: date-time
        context:
          $ref: "#/components/schemas/Context"
        actor:
          $ref: "#/components/schemas/Actor"
        category:
          type: string
          example: "report"
        action:
          type: string
          example: "report.view"
        targets:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
          example:
            - type: "report"
              name: "sign-in-attempts"
            - type: "user"

    Client:
      type: object
      description: Information about the client used by an actor to initiate an action.
      required:
        - name
        - version
      properties:
        name:
          type: string
        version:
          type: string
    Context:
      type: object
      description: Additional information about the initiator of an action.
      required:
        - account
        - origin
        - location
      properties:
        account:
          $ref: "#/components/schemas/ContextAccount"
        origin:
          type: string
        session:
          $ref: "#/components/schemas/Session"
        location:
          $ref: "#/components/schemas/Location"
        device:
          $ref: "#/components/schemas/Device"
        client:
          $ref: "#/components/schemas/Client"
        os:
          $ref: "#/components/schemas/OS"
        userAgent:
          type: string
      example:
        account:
          uuid: "3JPKX6XC6BDDBJGJYCLOSVXQE4"
          name: "Some Account Name"
        origin: "password_manager"
        session:
          uuid: "UFR7T3I2FZAQ5GGFYQIY7YUGKE"
          login_time: "2025-01-01T00:00:00Z"
        location:
          ip_address: "192.168.1.1"
          country: "Canada"
          region: "Ontario"
          city: "Toronto"
          latitude: 43.65
          longitude: 79.38
        device:
          uuid: "voruqc6amjy4gs4oh2qs3fw4i4"
          model: "141.0"
        client:
          name: "1Password Extension"
          version: "81104027"
        os:
          name: "MacOSX"
          version: "10.15"
        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Safari/605.1.15"
    ContextAccount:
      type: object
      description: "Information about the account initiating the event"
      required:
        - uuid
        - name
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        name:
          type: string
          example: "Some Account Name"
    Device:
      type: object
      description: A description of the device used to initiate an action.
      required:
        - uuid
        - model
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        model:
          type: string
    Entity:
      type: object
      description: An entity which was affected by a given event.
      required:
        - type
        - payload
      properties:
        type:
          $ref: "#/components/schemas/EntityType"
        payload:
          type: object
    EntityType:
      type: string
      description: The type of an entity affected by a given event. An entity may contain a number of additional properties specific to its type.
    Error:
      type: object
      description: A generic error.
      properties:
        Error:
          type: object
          properties:
            Message:
              type: string
              description: The error message.
              example: "An error occurred while processing the request."
    Location:
      type: object
      description: A description of the geographical location where an event originated.
      required:
        - ip_address
      properties:
        ip_address:
          type: string
        country:
          type: string
        region:
          type: string
        city:
          type: string
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
    OS:
      type: object
      description: The operating system from which an event originated.
      required:
        - name
        - version
      properties:
        name:
          type: string
        version:
          type: string
    Session:
      type: object
      description: The session from which an event originated.
      required:
        - uuid
        - login_time
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        login_time:
          type: string
          format: date-time
    UUID:
      type: string
      description: A generic UUID.
      example: "56YE2TYN2VFYRLNSHKPW5NVT5E"
  responses:
    AuditEventsResponse:
      description: Audit events response object
      # RateLimit headers are set by middleware, not defined here
      content:
        application/json:
          schema:
            type: object
            required:
              - data
              - meta
            properties:
              data:
                type: object
                description: A subset of the requested events data.
                required:
                  - audit_events
                properties:
                  audit_events:
                    type: array
                    items:
                      $ref: "#/components/schemas/AuditEvent"
              meta:
                type: object
                description: Response metadata which may be used as input to subsequent requests.
                required:
                  - has_more
                properties:
                  next_page_token:
                    type: string
                    description: >
                      An opaque token used to specify the next page of results to retrieve. Should be included in subsequent requests until has_more is false.
                    example: "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
                  has_more:
                    type: boolean
                    description: >
                      True if and only if there are additional pages of results available for retrieval. Indicates that additional requests are required to
                      retrieve the full result set.
    GenericErrorResponse:
      description: Generic error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnauthorizedErrorResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    TooManyRequestsResponse:
      description: Too Many Requests"
      headers:
        Retry-After:
          schema:
            type: integer
          description: "The number of seconds until requests from this client will be allowed again."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
