openapi: 3.0.1
info:
  title: Events API
  description: 1Password Events API Specification.
  version: 3.0.0
  contact:
    name: 1Password Support
    email: support@1password.com
    url: https://1password.com/contact-support
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:
      description: >-
        Returns a paginated list of audit events describing actions taken by
        team members in the authenticated 1Password account. Use optional time
        bounds and the pagination parameters to page through results.
      summary: >-
        Retrieves audit events for actions performed by team members within a
        1Password account.
      tags:
        - api-v3
      operationId: ListAuditEvents
      security:
        - Jwt-saBearerAuth: []
      parameters:
        - in: query
          name: max_page_size
          description: The maximum number of results to return in a single request.
          schema:
            type: integer
            default: 100
            minimum: 0
        - in: query
          name: page_token
          description: An opaque token identifying the next page of results to retrieve.
          schema:
            type: string
        - in: query
          name: start_time
          description: >-
            The lower bound insertion time for which to retrieve results,
            filtering on when events were ingested, not when they occurred. This
            bound is exclusive: only events whose insertion time is strictly
            greater than start_time are returned. Invalid if page_token is
            specified.
          schema:
            type: string
            format: date-time
        - in: query
          name: end_time
          description: >-
            The upper bound insertion time for which to retrieve results,
            filtering on when events were ingested, not when they occurred. This
            bound is exclusive: only events whose insertion time is strictly
            less than end_time are returned. Invalid if page_token is specified.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          $ref: '#/components/responses/AuditEventsResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '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
      description: Bearer authentication using a JWT issued for a service account.
  schemas:
    Account:
      type: object
      description: An account associated with a given event.
      example:
        id: 56YE2TYN2VFYRLNSHKPW5NVT5E
        name: Some Account Name
        state: A
        type: B
        domain: domain.com
      required:
        - id
        - name
        - state
        - type
        - domain
      properties:
        id:
          $ref: '#/components/schemas/Id'
        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
        id: 56YE2TYN2VFYRLNSHKPW5NVT5E
        name: Some User
        email: user.email@domain.com
        linked_account:
          id: 3JPKX6XC6BDDBJGJYCLOSVXQE4
          name: Some Account Name
          state: A
          type: B
          domain: domain.com
      required:
        - type
        - id
      properties:
        type:
          type: string
        id:
          $ref: '#/components/schemas/Id'
        name:
          type: string
        email:
          type: string
          format: email
        linked_account:
          $ref: '#/components/schemas/Account'
    AuditEvent:
      type: object
      required:
        - id
        - create_time
        - insert_time
        - context
        - actor
        - category
        - action
        - targets
      description: A single audit event object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        create_time:
          type: string
          format: date-time
          description: The time the event occurred.
        insert_time:
          type: string
          format: date-time
          description: The time the event was received and stored by 1Password.
        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
              payload:
                name: sign-in-attempts
            - type: user
              payload: {}
        diff:
          $ref: '#/components/schemas/Diff'
        correlation_id:
          type: string
          description: >-
            An optional identifier shared by audit events that originated from
            the same bulk action.
          example: C7VYQXG3CZGBVHR2YOL5LXKNJI
    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'
        user_agent:
          type: string
      example:
        account:
          id: 3JPKX6XC6BDDBJGJYCLOSVXQE4
          name: Some Account Name
        origin: password_manager
        session:
          id: UFR7T3I2FZAQ5GGFYQIY7YUGKE
          login_time: '2025-01-01T00:00:00Z'
        location:
          ip_address: 192.168.1.1
          region_code: CA
          city: Toronto
          latitude: 43.65
          longitude: 79.38
        device:
          id: voruqc6amjy4gs4oh2qs3fw4i4
          model: '141.0'
          name: Safari
        client:
          name: 1Password Extension
          version: '81104027'
        os:
          name: MacOSX
          version: '10.15'
        user_agent: >-
          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:
        - id
        - name
      properties:
        id:
          $ref: '#/components/schemas/Id'
        name:
          type: string
          example: Some Account Name
    Device:
      type: object
      description: A description of the device used to initiate an action.
      required:
        - id
        - model
        - name
      properties:
        id:
          $ref: '#/components/schemas/Id'
        model:
          type: string
        name:
          type: string
    Diff:
      type: object
      description: A description of the change made by a given event.
      required:
        - type
        - old_value
        - new_value
      properties:
        type:
          $ref: '#/components/schemas/DiffType'
        old_value:
          type: object
        new_value:
          type: object
      example:
        type: account-change
        old_value:
          type: B
        new_value:
          type: F
    DiffType:
      type: string
      description: The type of change made by a given event.
    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.
      required:
        - type
        - message
      properties:
        type:
          type: string
          description: >-
            A machine-readable error type identifier. Values are Connect/gRPC
            status code names per AEP-193.
          example: unauthenticated
        message:
          type: string
          description: A human-readable description of the error.
          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
        region_code:
          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:
        - id
        - login_time
      properties:
        id:
          $ref: '#/components/schemas/Id'
        login_time:
          type: string
          format: date-time
    Id:
      type: string
      description: A generic identifier.
      example: 56YE2TYN2VFYRLNSHKPW5NVT5E
  responses:
    AuditEventsResponse:
      description: Audit events response object
      content:
        application/json:
          example:
            audit_events: []
          schema:
            type: object
            required:
              - audit_events
            properties:
              audit_events:
                type: array
                description: A subset of the requested audit events.
                items:
                  $ref: '#/components/schemas/AuditEvent'
              next_page_token:
                type: string
                description: >
                  An opaque token used to retrieve the next page of results.
                  Present only when additional results are available; absence
                  indicates the final page.
                example: aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK
    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'