openapi: 3.0.0
info:
  title: Events API
  description: 1Password Events API Specification.
  version: 1.4.1
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
paths:
  /api/auth/introspect:
    get:
      x-mint:
        href: "/events-api/reference/introspect-v1"
      summary: Performs introspection of the provided Bearer JWT token
      deprecated: true
      tags:
        - auth
      security:
        - jwtsa: []
      operationId: getAuthIntrospect
      responses:
        "200":
          $ref: "#/components/responses/IntrospectResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
  /api/v2/auth/introspect:
    get:
      x-mint:
        href: "/events-api/reference/introspect"
        metadata:
          sidebarTitle: "Introspect (v2)"
          description: "Performs introspection of the provided Bearer JWT token"
      summary: Introspect bearer token (v2)
      tags:
        - auth
      security:
        - jwtsa: []
      operationId: getAuthIntrospectV2
      responses:
        "200":
          $ref: "#/components/responses/IntrospectV2Response"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
  /api/v1/signinattempts:
    post:
      x-mint:
        href: "/events-api/reference/sign-in-attempt-v1"
      summary: Retrieves events for both successful and failed attempts to sign into a 1Password account
      description: This endpoint requires your JSON Web Token to have the *signinattempts* feature.
      tags:
        - api-v1
      security:
        - jwtsa: []
      operationId: getSignInAttempts
      requestBody:
        $ref: "#/components/requestBodies/SignInAttemptsRequest"
      responses:
        "200":
          $ref: "#/components/responses/SignInAttemptsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
  /api/v2/signinattempts:
    post:
      x-mint:
        href: "/events-api/reference/sign-in-attempt"
        metadata:
          sidebarTitle: "Sign-in attempts (v2)"
          description: "Retrieves events for both successful and failed attempts to sign into a 1Password account"
      summary: Retrieve sign-in attempts (v2)
      description: This endpoint requires your JSON Web Token to have the *signinattempts* feature.
      tags:
        - api-v2
      security:
        - jwtsa: []
      operationId: getSignInAttemptsV2
      requestBody:
        $ref: "#/components/requestBodies/SignInAttemptsRequest"
      responses:
        "200":
          $ref: "#/components/responses/SignInAttemptsV2Response"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
  /api/v1/itemusages:
    post:
      x-mint:
        href: "/events-api/reference/items-usage-v1"
      summary: Retrieves events for each usage of an item stored in a shared vault within a 1Password account
      description: "This endpoint requires your JSON Web Token to have the *itemusages* feature."
      tags:
        - api-v1
      security:
        - jwtsa: []
      operationId: getItemUsages
      requestBody:
        $ref: "#/components/requestBodies/ItemUsagesRequest"
      responses:
        "200":
          $ref: "#/components/responses/ItemUsagesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
  /api/v2/itemusages:
    post:
      x-mint:
        href: "/events-api/reference/items-usage"
        metadata:
          sidebarTitle: "Item usages (v2)"
          description: "Retrieves events for each usage of an item stored in a shared vault within a 1Password account"
      summary: Retrieve item usages (v2)
      description: "This endpoint requires your JSON Web Token to have the *itemusages* feature."
      tags:
        - api-v2
      security:
        - jwtsa: []
      operationId: getItemUsagesV2
      requestBody:
        $ref: "#/components/requestBodies/ItemUsagesRequest"
      responses:
        "200":
          $ref: "#/components/responses/ItemUsagesV2Response"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
  /api/v1/auditevents:
    post:
      x-mint:
        href: "/events-api/reference/audit-events-v1"
      summary: Retrieves audit events for actions performed by team members within a 1Password account
      description: "This endpoint requires your JSON Web Token to have the *auditevents* feature."
      tags:
        - api-v1
      security:
        - jwtsa: []
      operationId: getAuditEvents
      requestBody:
        $ref: "#/components/requestBodies/AuditEventsRequest"
      responses:
        "200":
          $ref: "#/components/responses/AuditEventsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
  /api/v2/auditevents:
    post:
      x-mint:
        href: "/events-api/reference/audit-events"
        metadata:
          sidebarTitle: "Audit events (v2)"
          description: "Retrieves audit events for actions performed by team members within a 1Password account"
      summary: Retrieve audit events (v2)
      description: "This endpoint requires your JSON Web Token to have the *auditevents* feature."
      tags:
        - api-v2
      security:
        - jwtsa: []
      operationId: getAuditEventsV2
      requestBody:
        $ref: "#/components/requestBodies/AuditEventsRequest"
      responses:
        "200":
          $ref: "#/components/responses/AuditEventsV2Response"
        "401":
          $ref: "#/components/responses/UnauthorizedErrorResponse"
        "500":
          $ref: "#/components/responses/InternalServerErrorResponse"
        default:
          $ref: "#/components/responses/GenericErrorResponse"
components:
  securitySchemes:
    jwtsa:
      type: http
      description: A JWT SA token issued to this service
      scheme: bearer
      bearerFormat: JWT-SA
  schemas:
    Introspection:
      type: object
      properties:
        UUID:
          type: string
        IssuedAt:
          $ref: "#/components/schemas/DateTimeRFC3339"
        Features:
          type: array
          items:
            type: string
          example: ["auditevents", "itemusages", "signinattempts"]
    IntrospectionV2:
      type: object
      properties:
        uuid:
          type: string
        issued_at:
          $ref: "#/components/schemas/DateTimeRFC3339"
        features:
          type: array
          items:
            type: string
          example: ["auditevents", "itemusages", "signinattempts"]
        account_uuid:
          type: string
    CursorCollection:
      description: Common cursor properties for collection responses
      allOf:
        - $ref: "#/components/schemas/Cursor"
        - properties:
            has_more:
              description: Whether there may still be more data to fetch using the returned cursor. If true, the subsequent request could still be empty.
              type: boolean
    SignInAttempt:
      description: A single sign-in attempt object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        session_uuid:
          $ref: "#/components/schemas/UUID"
        timestamp:
          $ref: "#/components/schemas/DateTimeRFC3339"
        category:
          type: string
          enum:
            [
              success,
              credentials_failed,
              mfa_failed,
              sso_failed,
              modern_version_failed,
              firewall_failed,
              firewall_reported_success,
            ]
          example: "firewall_failed"
        type:
          type: string
          enum:
            [
              credentials_ok,
              mfa_ok,
              federated,
              password_secret_bad,
              mfa_missing,
              totp_disabled,
              totp_bad,
              totp_timeout,
              u2f_disabled,
              u2f_bad,
              u2f_timout,
              duo_disabled,
              duo_bad,
              duo_timeout,
              duo_native_bad,
              service_account_sso_denied,
              non_sso_user,
              sso_user_mismatch,
              platform_secret_disabled,
              platform_secret_bad,
              platform_secret_proxy,
              code_disabled,
              code_bad,
              code_timeout,
              ip_blocked,
              continent_blocked,
              country_blocked,
              anonymous_blocked,
              all_blocked,
              modern_version_missing,
              modern_version_old,
            ]
          example: "continent_blocked"
        country:
          type: string
          description: Country ISO Code
          example: "France"
        details:
          $ref: "#/components/schemas/Details"
        target_user:
          $ref: "#/components/schemas/User"
        client:
          $ref: "#/components/schemas/Client"
        location:
          $ref: "#/components/schemas/Location"
    SignInAttemptItems:
      description: An object wrapping cursor properties and a list of sign-in attempts
      allOf:
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/SignInAttempt"
        - $ref: "#/components/schemas/CursorCollection"
    SignInAttemptV2:
      description: A single sign-in attempt object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        session_uuid:
          $ref: "#/components/schemas/UUID"
        timestamp:
          $ref: "#/components/schemas/DateTimeRFC3339"
        category:
          type: string
          enum:
            [
              success,
              credentials_failed,
              mfa_failed,
              sso_failed,
              modern_version_failed,
              firewall_failed,
              firewall_reported_success,
            ]
          example: "firewall_failed"
        type:
          type: string
          enum:
            [
              credentials_ok,
              mfa_ok,
              federated,
              password_secret_bad,
              mfa_missing,
              totp_disabled,
              totp_bad,
              totp_timeout,
              u2f_disabled,
              u2f_bad,
              u2f_timout,
              duo_disabled,
              duo_bad,
              duo_timeout,
              duo_native_bad,
              service_account_sso_denied,
              non_sso_user,
              sso_user_mismatch,
              platform_secret_disabled,
              platform_secret_bad,
              platform_secret_proxy,
              code_disabled,
              code_bad,
              code_timeout,
              ip_blocked,
              continent_blocked,
              country_blocked,
              anonymous_blocked,
              all_blocked,
              modern_version_missing,
              modern_version_old,
            ]
          example: "continent_blocked"
        country:
          type: string
          description: Country ISO Code
          example: "France"
        details:
          $ref: "#/components/schemas/Details"
        target_user:
          $ref: "#/components/schemas/UserV2"
        client:
          $ref: "#/components/schemas/Client"
        location:
          $ref: "#/components/schemas/Location"
        account_uuid:
          $ref: "#/components/schemas/UUID"
    SignInAttemptItemsV2:
      description: An object wrapping cursor properties and a list of sign-in attempts
      allOf:
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/SignInAttemptV2"
        - $ref: "#/components/schemas/CursorCollection"
    SignInAttemptUserTypes:
      type: string
      enum:
        - "user"
        - "external_user"
    ItemUsage:
      description: A single item usage object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        timestamp:
          $ref: "#/components/schemas/DateTimeRFC3339"
        used_version:
          type: integer
        vault_uuid:
          $ref: "#/components/schemas/UUID"
        item_uuid:
          $ref: "#/components/schemas/UUID"
        action:
          type: string
          enum:
            [
              fill,
              select-sso-provider,
              enter-item-edit-mode,
              export,
              share,
              secure-copy,
              reveal,
              server-create,
              server-update,
              server-fetch,
            ]
          example: "reveal"
        user:
          $ref: "#/components/schemas/User"
        client:
          $ref: "#/components/schemas/Client"
        location:
          $ref: "#/components/schemas/Location"
    ItemUsageV2:
      description: A single item usage object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        timestamp:
          $ref: "#/components/schemas/DateTimeRFC3339"
        used_version:
          type: integer
        vault_uuid:
          $ref: "#/components/schemas/UUID"
        item_uuid:
          $ref: "#/components/schemas/UUID"
        action:
          type: string
          enum:
            [
              fill,
              select-sso-provider,
              enter-item-edit-mode,
              export,
              share,
              secure-copy,
              reveal,
              server-create,
              server-update,
              server-fetch,
            ]
          example: "reveal"
        user:
          $ref: "#/components/schemas/UserV2"
        client:
          $ref: "#/components/schemas/Client"
        location:
          $ref: "#/components/schemas/Location"
        account_uuid:
          $ref: "#/components/schemas/UUID"
    ItemUsageItems:
      description: An object wrapping cursor properties and a list of items usages
      allOf:
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/ItemUsage"
        - $ref: "#/components/schemas/CursorCollection"
    ItemUsageItemsV2:
      description: An object wrapping cursor properties and a list of items usages
      allOf:
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/ItemUsageV2"
        - $ref: "#/components/schemas/CursorCollection"
    AuditEvent:
      description: A single audit event object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        timestamp:
          $ref: "#/components/schemas/DateTimeRFC3339"
        actor_uuid:
          $ref: "#/components/schemas/UUID"
        actor_details:
          $ref: "#/components/schemas/User"
        action:
          $ref: "#/components/schemas/AuditEventActions"
        object_type:
          $ref: "#/components/schemas/AuditEventObjectTypes"
        object_uuid:
          $ref: "#/components/schemas/UUID"
        object_details:
          $ref: "#/components/schemas/User"
        aux_id:
          type: integer
        aux_uuid:
          $ref: "#/components/schemas/UUID"
        aux_details:
          $ref: "#/components/schemas/User"
        aux_info:
          type: string
        session:
          $ref: "#/components/schemas/Session"
        location:
          $ref: "#/components/schemas/Location"
    AuditEventV2:
      description: A single audit event object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        timestamp:
          $ref: "#/components/schemas/DateTimeRFC3339"
        actor_uuid:
          $ref: "#/components/schemas/UUID"
        actor_details:
          $ref: "#/components/schemas/User"
        actor_type:
          $ref: "#/components/schemas/AuditEventActorTypes"
        actor_account_uuid:
          $ref: "#/components/schemas/UUID"
        account_uuid:
          $ref: "#/components/schemas/UUID"
        action:
          $ref: "#/components/schemas/AuditEventActions"
        object_type:
          $ref: "#/components/schemas/AuditEventObjectTypes"
        object_uuid:
          $ref: "#/components/schemas/UUID"
        object_details:
          $ref: "#/components/schemas/User"
        aux_id:
          type: integer
        aux_uuid:
          $ref: "#/components/schemas/UUID"
        aux_details:
          $ref: "#/components/schemas/User"
        aux_info:
          type: string
        session:
          $ref: "#/components/schemas/Session"
        location:
          $ref: "#/components/schemas/Location"
    AuditEventItems:
      description: An object wrapping cursor properties and a list of audit events
      allOf:
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/AuditEvent"
        - $ref: "#/components/schemas/CursorCollection"
    AuditEventItemsV2:
      description: An object wrapping cursor properties and a list of audit events
      allOf:
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/AuditEventV2"
        - $ref: "#/components/schemas/CursorCollection"
    AuditEventActions:
      type: string
      enum:
        - "activate"
        - "update"
        - "delete"
        - "convert"
        - "enblduo"
        - "updatduo"
        - "disblduo"
        - "rdmchild"
        - "detchild"
        - "dlgsess"
        - "create"
        - "deolddev"
        - "dealldev"
        - "reauth"
        - "begin"
        - "complete"
        - "propose"
        - "updatfw"
        - "join"
        - "leave"
        - "role"
        - "purge"
        - "view"
        - "export"
        - "replace"
        - "grant"
        - "revoke"
        - "share"
        - "delshare"
        - "uisas"
        - "enblmfa"
        - "updatmfa"
        - "disblmfa"
        - "musercom"
        - "muserdec"
        - "sendpkg"
        - "resendts"
        - "prsndall"
        - "trename"
        - "tverify"
        - "trevoke"
        - "ssotknv"
        - "enblsso"
        - "disblsso"
        - "chngpsso"
        - "chngasso"
        - "chngdsso"
        - "delgsso"
        - "addgsso"
        - "cancel"
        - "hide"
        - "unhide"
        - "upguest"
        - "verify"
        - "reactive"
        - "suspend"
        - "beginr"
        - "provsn"
        - "sendts"
        - "unknown"
        - "completr"
        - "cancelr"
        - "trvlaway"
        - "trvlback"
        - "changeks"
        - "changemp"
        - "changesk"
        - "changenm"
        - "changela"
        - "tdvcsso"
        - "sdvcsso"
        - "patch"
        - "updatea"
        - "vrfydmn"
        - "uvrfydmn"
        - "dvrfydmn"
        - "expire"
        - "launchi"
        - "unlink"
    AuditEventObjectTypes:
      type: string
      enum:
        - "account"
        - "user"
        - "device"
        - "group"
        - "gm"
        - "vault"
        - "item"
        - "items"
        - "itemhist"
        - "vaultkey"
        - "template"
        - "uva"
        - "gva"
        - "invite"
        - "ec"
        - "miguser"
        - "sso"
        - "sub"
        - "card"
        - "pm"
        - "slackapp"
        - "file"
        - "famchild"
        - "sa"
        - "satoken"
        - "dlgdsess"
        - "ssotkn"
        - "report"
        - "cred"
        - "mngdacc"
    AuditEventActorTypes:
      type: string
      enum:
        - "user"
        - "external_user"
    ResetCursor:
      description: Reset cursor
      properties:
        limit:
          type: number
          minimum: 1
          maximum: 1000
        start_time:
          $ref: "#/components/schemas/DateTimeRFC3339"
        end_time:
          $ref: "#/components/schemas/DateTimeRFC3339"
    Cursor:
      description: Cursor
      properties:
        cursor:
          description: Cursor to fetch more data if available or continue the polling process if required
          type: string
          example: "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK"
    User:
      description: User object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        name:
          description: Full name
          type: string
          example: "Jack O'Neill"
        email:
          type: string
          format: email
    UserV2:
      description: User object
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        name:
          description: Full name
          type: string
          example: "Jack O'Neill"
        email:
          type: string
          format: email
        user_type:
          $ref: "#/components/schemas/SignInAttemptUserTypes"
        user_account_uuid:
          $ref: "#/components/schemas/UUID"
    Location:
      description: Geolocation Info about the client
      properties:
        country:
          type: string
          example: "CA"
        region:
          type: string
          example: "Ontario"
        city:
          type: string
          example: "Toronto"
        longitude:
          type: number
          example: 43.64
        latitude:
          type: number
          example: -79.433
    Client:
      description: Metadata gathered about the client
      properties:
        app_name:
          type: string
          example: 1Password Extension
        app_version:
          type: string
          example: "20127"
        platform_name:
          type: string
          example: "Chrome"
        platform_version:
          description: Depending on the platform used, this can be the version of the browser that the client extension is installed, the model of computer that the native application is installed or the machine's CPU version that the CLI was installed
          type: string
        os_name:
          type: string
          example: MacOSX
        os_version:
          type: string
          example: "10.15.6"
        ip_address:
          type: string
          example: "13.227.95.22"
    Session:
      description: Session information gathered about the client
      properties:
        uuid:
          $ref: "#/components/schemas/UUID"
        login_time:
          $ref: "#/components/schemas/DateTimeRFC3339"
        device_uuid:
          $ref: "#/components/schemas/UUID"
        ip:
          type: string
          example: "13.227.95.22"
    Details:
      description: Additional information about the sign-in attempt
      properties:
        value:
          description: For firewall prevented sign-ins, the value is the chosen continent, country, etc. that blocked the sign-in attempt
          type: string
          example: "Europe"
    UUID:
      type: string
      example: "56YE2TYN2VFYRLNSHKPW5NVT5E"
    DateTimeRFC3339:
      type: string
      format: "date-time"
      example: "2020-06-11T16:32:50-03:00"
    Error:
      type: object
      properties:
        Error:
          type: object
          properties:
            Message:
              type: string
              description: The error message.
  requestBodies:
    SignInAttemptsRequest:
      $ref: "#/components/requestBodies/CursorRequest"
    ItemUsagesRequest:
      $ref: "#/components/requestBodies/CursorRequest"
    AuditEventsRequest:
      $ref: "#/components/requestBodies/CursorRequest"
    CursorRequest:
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/Cursor"
              - $ref: "#/components/schemas/ResetCursor"
          examples:
            Continuing cursor:
              $ref: "#/components/examples/Cursor"
            Resetting cursor:
              $ref: "#/components/examples/ResetCursor"
  responses:
    SignInAttemptsResponse:
      description: Sign-in attempts response object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SignInAttemptItems"
    SignInAttemptsV2Response:
      description: Sign-in attempts response object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SignInAttemptItemsV2"
    ItemUsagesResponse:
      description: Item usages response object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ItemUsageItems"
    ItemUsagesV2Response:
      description: Item usages response object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ItemUsageItemsV2"
    AuditEventsResponse:
      description: Audit events response object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuditEventItems"
    AuditEventsV2Response:
      description: Audit events response object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AuditEventItemsV2"
    UnauthorizedErrorResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    IntrospectResponse:
      description: Introspection object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Introspection"
    IntrospectV2Response:
      description: Introspection v2 object
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/IntrospectionV2"
    GenericErrorResponse:
      description: Generic error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  examples:
    Cursor:
      summary: Used for continued calling with a cursor
      value: { "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" }
    ResetCursor:
      summary: Used for reseting the cursor
      value: { "limit": 100, "start_time": "2021-06-11T16:32:50-03:00" }