1Password Events API

openapi: 3.1.0
info:
  title: 1Password Events API
  description: The 1Password Events API provides programmatic access to event data
    generated within a 1Password account. It enables security teams and administrators
    to retrieve sign-in attempts, item usage records, and audit events for monitoring,
    compliance, and security analysis. The API uses cursor-based pagination with POST
    requests to efficiently stream large volumes of event data.
  version: 2.0.0
  contact:
    name: 1Password Support
    url: https://support.1password.com/
  termsOfService: https://1password.com/legal/terms-of-service/
externalDocs:
  description: 1Password Events API Reference
  url: https://developer.1password.com/docs/events-api/reference/
servers:
- url: https://events.1password.com
  description: 1Password Events API server (US). Replace with the appropriate base
    URL for your 1Password account region.
tags:
- name: Audit Events
  description: Retrieve information about actions performed by team members within
    a 1Password account, including when an action was performed and by whom, along
    with details about the type and object of the action.
- name: Introspection
  description: Retrieve information about the authentication token being used, including
    its features and permissions.
- name: Item Usages
  description: Retrieve information about items in shared vaults that have been modified,
    accessed, or used, including the user who accessed the item, when it was accessed,
    and the vault where the item is stored.
- name: Sign-In Attempts
  description: Retrieve information about sign-in attempts to 1Password accounts,
    including the name and IP address of the user who attempted to sign in, when the
    attempt was made, and for failed attempts the cause of failure.
security:
- bearerAuth: []
paths:
  /api/v2/signinattempts:
    post:
      operationId: listSignInAttemptsV2
      summary: 1Password List Sign-in Attempts
      description: Returns information about sign-in attempts to 1Password accounts.
        Each record includes the name and IP address of the user who attempted to
        sign in, when the attempt was made, the type of sign-in, the country, and
        for failed attempts the cause of failure. The request must include either
        a cursor from a previous response or a ResetCursor object with a start time.
      tags:
      - Sign-In Attempts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventRequest'
      responses:
        '200':
          description: Successfully retrieved sign-in attempts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInAttemptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/itemusages:
    post:
      operationId: listItemUsagesV2
      summary: 1Password List Item Usages
      description: Returns information about items in shared vaults that have been
        modified, accessed, or used. Each record includes the name and IP address
        of the user who accessed the item, when the item was accessed, the action
        performed, the vault where the item is stored, and item details. The request
        must include either a cursor from a previous response or a ResetCursor object
        with a start time.
      tags:
      - Item Usages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventRequest'
      responses:
        '200':
          description: Successfully retrieved item usages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemUsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/auditevents:
    post:
      operationId: listAuditEventsV2
      summary: 1Password List Audit Events
      description: Returns information about actions performed by team members within
        a 1Password account. Each record includes when an action was performed and
        by whom, along with details about the type and object of the action. The request
        must include either a cursor from a previous response or a ResetCursor object
        with a start time.
      tags:
      - Audit Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventRequest'
      responses:
        '200':
          description: Successfully retrieved audit events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1/introspect:
    get:
      operationId: introspectToken
      summary: 1Password Introspect Authentication Token
      description: Returns information about the token used for authentication, including
        its UUID, features, and the account it belongs to.
      tags:
      - Introspection
      responses:
        '200':
          description: Successfully retrieved token information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenIntrospection'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An Events API bearer token generated from 1Password. Each request
        must include this token in the Authorization header. The token must have the
        appropriate feature permissions for the endpoint being accessed.
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    EventRequest:
      type: object
      description: The request body for fetching events. Must include either a cursor
        string from a previous response to continue pagination, or a ResetCursor object
        to start fetching from a specific time.
      properties:
        limit:
          type: integer
          description: The maximum number of event records to return per page.
          minimum: 1
          maximum: 1000
          default: 100
        cursor:
          type: string
          description: A cursor from a previous response to continue fetching events
            from where the last request left off.
        start_time:
          type: string
          format: date-time
          description: An ISO 8601 timestamp to begin fetching events from a specific
            time. Used to create a new cursor starting from this point.
    SignInAttemptResponse:
      type: object
      description: The response containing sign-in attempt records and a cursor for
        pagination.
      properties:
        cursor:
          type: string
          description: A cursor to use in the next request to continue fetching events.
        has_more:
          type: boolean
          description: Whether there are more events available to fetch using the
            cursor.
        items:
          type: array
          description: The list of sign-in attempt records.
          items:
            $ref: '#/components/schemas/SignInAttempt'
    SignInAttempt:
      type: object
      description: Represents a single sign-in attempt to a 1Password account.
      properties:
        uuid:
          type: string
          format: uuid
          description: The unique identifier for the sign-in attempt.
        session_uuid:
          type: string
          format: uuid
          description: The UUID of the session associated with the sign-in attempt.
        timestamp:
          type: string
          format: date-time
          description: When the sign-in attempt occurred.
        category:
          type: string
          description: The category of the sign-in attempt.
          enum:
          - success
          - credentials_failed
          - mfa_failed
          - modern_version_required
          - sso_failed
        type:
          type: string
          description: The type of sign-in method used.
          enum:
          - credentials_ok
          - mfa_ok
          - password_secret_bad
          - mfa_missing
          - totp_disabled
          - totp_bad
          - u2f_failed
          - duo_failed
          - duo_native_failed
          - sso_failed
        country:
          type: string
          description: The two-letter ISO country code of the sign-in location.
          minLength: 2
          maxLength: 2
        target_user:
          $ref: '#/components/schemas/EventUser'
        client:
          $ref: '#/components/schemas/EventClient'
    ItemUsageResponse:
      type: object
      description: The response containing item usage records and a cursor for pagination.
      properties:
        cursor:
          type: string
          description: A cursor to use in the next request to continue fetching events.
        has_more:
          type: boolean
          description: Whether there are more events available to fetch using the
            cursor.
        items:
          type: array
          description: The list of item usage records.
          items:
            $ref: '#/components/schemas/ItemUsage'
    ItemUsage:
      type: object
      description: Represents a record of an item in a shared vault being accessed,
        modified, or used.
      properties:
        uuid:
          type: string
          format: uuid
          description: The unique identifier for the item usage record.
        timestamp:
          type: string
          format: date-time
          description: When the item was accessed.
        used_version:
          type: integer
          description: The version of the item that was used.
        vault_uuid:
          type: string
          format: uuid
          description: The UUID of the vault containing the item.
        item_uuid:
          type: string
          format: uuid
          description: The UUID of the item that was used.
        action:
          type: string
          description: The type of action performed on the item.
          enum:
          - fill
          - copy
          - reveal
          - sso-fill
          - secure-copy
        user:
          $ref: '#/components/schemas/EventUser'
        client:
          $ref: '#/components/schemas/EventClient'
        location:
          $ref: '#/components/schemas/EventLocation'
    AuditEventResponse:
      type: object
      description: The response containing audit event records and a cursor for pagination.
      properties:
        cursor:
          type: string
          description: A cursor to use in the next request to continue fetching events.
        has_more:
          type: boolean
          description: Whether there are more events available to fetch using the
            cursor.
        items:
          type: array
          description: The list of audit event records.
          items:
            $ref: '#/components/schemas/AuditEvent'
    AuditEvent:
      type: object
      description: Represents an audit event recording an action performed by a team
        member within the 1Password account.
      properties:
        uuid:
          type: string
          format: uuid
          description: The unique identifier for the audit event.
        timestamp:
          type: string
          format: date-time
          description: When the action was performed.
        actor_uuid:
          type: string
          format: uuid
          description: The UUID of the user who performed the action.
        actor_details:
          $ref: '#/components/schemas/EventUser'
        action:
          type: string
          description: The type of action that was performed.
        object_type:
          type: string
          description: The type of object the action was performed on.
        object_uuid:
          type: string
          format: uuid
          description: The UUID of the object the action was performed on.
        object_details:
          type: object
          description: Additional details about the object of the action.
        aux_id:
          type: integer
          description: An auxiliary identifier providing additional context.
        aux_uuid:
          type: string
          format: uuid
          description: An auxiliary UUID providing additional context.
        aux_details:
          type: object
          description: Additional auxiliary details about the event.
        aux_info:
          type: string
          description: Additional auxiliary information about the event.
        session:
          type: object
          description: Information about the session in which the action occurred.
          properties:
            uuid:
              type: string
              format: uuid
              description: The UUID of the session.
            login_time:
              type: string
              format: date-time
              description: When the session was created.
            device_uuid:
              type: string
              format: uuid
              description: The UUID of the device used.
            ip:
              type: string
              description: The IP address of the client.
        location:
          $ref: '#/components/schemas/EventLocation'
    EventUser:
      type: object
      description: Represents a user involved in an event.
      properties:
        uuid:
          type: string
          format: uuid
          description: The unique identifier of the user.
        name:
          type: string
          description: The name of the user.
        email:
          type: string
          format: email
          description: The email address of the user.
    EventClient:
      type: object
      description: Information about the client application used in an event.
      properties:
        app_name:
          type: string
          description: The name of the 1Password application.
        app_version:
          type: string
          description: The version of the application.
        platform_name:
          type: string
          description: The name of the operating system platform.
        platform_version:
          type: string
          description: The version of the operating system.
        os_name:
          type: string
          description: The name of the operating system.
        os_version:
          type: string
          description: The version of the operating system.
        ip:
          type: string
          description: The IP address of the client.
    EventLocation:
      type: object
      description: Geographic location information associated with an event.
      properties:
        country:
          type: string
          description: The two-letter ISO country code.
          minLength: 2
          maxLength: 2
        region:
          type: string
          description: The region or state.
        city:
          type: string
          description: The city name.
        latitude:
          type: number
          format: double
          description: The latitude coordinate.
        longitude:
          type: number
          format: double
          description: The longitude coordinate.
    TokenIntrospection:
      type: object
      description: Information about the bearer token used for authentication.
      properties:
        uuid:
          type: string
          format: uuid
          description: The unique identifier of the token.
        features:
          type: array
          description: The features and permissions the token has access to.
          items:
            type: string
            enum:
            - signinattempts
            - itemusages
            - auditevents
    Error:
      type: object
      description: Represents an error response from the Events API.
      properties:
        status:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: A human-readable error message.