openapi: 3.0.1
info:
  title: Passage by 1Password Management API
  description: >-
    Server-side REST Management API for Passage by 1Password, the passwordless /
    passkey authentication platform. Operations are scoped to a Passage application
    (app_id) and authenticated with a Bearer API key generated in the Passage
    Console (Settings -> API Keys). Covers user lifecycle (list, create, get,
    update, delete, activate, deactivate), WebAuthn device management, refresh-token
    revocation, and magic link creation. NOTE - 1Password has announced that the
    Passage product is being retired on 2026-01-16; this specification documents the
    API as published as of 2026-06-20.
  termsOfService: https://passage.1password.com
  contact:
    name: Passage by 1Password Support
    url: https://docs.passage.id/home
  version: '1.0'
servers:
  - url: https://api.passage.id/v1
    description: Passage Management API
security:
  - bearerAuth: []
tags:
  - name: Users
    description: User administration for a Passage app.
  - name: Devices
    description: WebAuthn (passkey) device management for a user.
  - name: Tokens
    description: Refresh-token management for a user.
  - name: Magic Links
    description: Magic link creation for passwordless login and identifier verification.
paths:
  /apps/{app_id}/users:
    get:
      operationId: listPaginatedUsers
      tags:
        - Users
      summary: List users
      description: >-
        Returns a paginated, filterable list of users for the app. Supports
        page/limit, created_before cursor, order_by, and identifier/id/login_count/
        status/created_at filters with prepended operators (e.g. identifier=<like:val>).
      parameters:
        - $ref: '#/components/parameters/AppID'
        - name: page
          in: query
          description: Page to fetch (min 1).
          schema:
            type: integer
            minimum: 1
        - name: limit
          in: query
          description: Number of users to fetch per page (max 500).
          schema:
            type: integer
            maximum: 500
        - name: created_before
          in: query
          description: Unix timestamp anchor; returns users created before the timestamp.
          schema:
            type: integer
        - name: order_by
          in: query
          description: 'Comma separated list of <field>:<ASC/DESC> (e.g. id:DESC,created_at:ASC). Cannot order_by identifier.'
          schema:
            type: string
        - name: identifier
          in: query
          description: Search users by email OR phone, with prepended operators (eq/ne/gt/lt/like/not_like).
          schema:
            type: string
        - name: id
          in: query
          description: Search users by id, with prepended operators.
          schema:
            type: string
        - name: login_count
          in: query
          description: Search users by login_count, with prepended operators.
          schema:
            type: integer
        - name: status
          in: query
          description: 'Search users by status. Valid values: active, inactive, pending.'
          schema:
            type: string
            enum: [active, inactive, pending]
      responses:
        '200':
          description: A paginated list of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaginatedUsersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      tags:
        - Users
      summary: Create a user
      description: >-
        Creates a new user from an email and/or phone identifier with optional
        user_metadata. Either email or phone is required; both may be provided.
      parameters:
        - $ref: '#/components/parameters/AppID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: The created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps/{app_id}/users/{user_id}:
    get:
      operationId: getUser
      tags:
        - Users
      summary: Get a user
      description: Returns a single user's full record, including WebAuthn devices and recent events.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateUser
      tags:
        - Users
      summary: Update a user
      description: Updates a user's email, phone, and/or user_metadata.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteUser
      tags:
        - Users
      summary: Delete a user
      description: Permanently deletes a user and their credentials.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
      responses:
        '200':
          description: The user was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{app_id}/users/{user_id}/activate:
    patch:
      operationId: activateUser
      tags:
        - Users
      summary: Activate a user
      description: Activates a user, allowing them to authenticate.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
      responses:
        '200':
          description: The activated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{app_id}/users/{user_id}/deactivate:
    patch:
      operationId: deactivateUser
      tags:
        - Users
      summary: Deactivate a user
      description: Deactivates a user, preventing them from authenticating.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
      responses:
        '200':
          description: The deactivated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{app_id}/users/{user_id}/devices:
    get:
      operationId: listUserDevices
      tags:
        - Devices
      summary: List a user's devices
      description: Returns the WebAuthn (passkey) devices registered to a user.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
      responses:
        '200':
          description: The user's WebAuthn devices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDevicesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{app_id}/users/{user_id}/devices/{device_id}:
    delete:
      operationId: deleteUserDevice
      tags:
        - Devices
      summary: Delete a user's device
      description: Removes a single WebAuthn (passkey) device from a user.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
        - name: device_id
          in: path
          required: true
          description: The ID of the WebAuthn device.
          schema:
            type: string
      responses:
        '200':
          description: The device was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{app_id}/users/{user_id}/tokens:
    delete:
      operationId: revokeUserRefreshTokens
      tags:
        - Tokens
      summary: Revoke a user's refresh tokens
      description: Revokes all of a user's active refresh tokens, signing them out across devices.
      parameters:
        - $ref: '#/components/parameters/AppID'
        - $ref: '#/components/parameters/UserID'
      responses:
        '200':
          description: The user's refresh tokens were revoked.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{app_id}/magic-links:
    post:
      operationId: createMagicLink
      tags:
        - Magic Links
      summary: Create a magic link
      description: >-
        Creates a magic link for login or identifier verification. Supply email or
        phone; set send=true (with channel) to have Passage deliver it, otherwise the
        embedded link is returned for your own delivery. If the user does not exist
        they are created first.
      parameters:
        - $ref: '#/components/parameters/AppID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMagicLinkRequest'
      responses:
        '201':
          description: The created magic link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MagicLinkResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Passage Management API key, sent as: Authorization: Bearer <PASSAGE_API_KEY>'
  parameters:
    AppID:
      name: app_id
      in: path
      required: true
      description: The Passage application ID.
      schema:
        type: string
    UserID:
      name: user_id
      in: path
      required: true
      description: The Passage user ID.
      schema:
        type: string
  responses:
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        error:
          type: string
        message:
          type: string
    CreateUserRequest:
      type: object
      description: Either email or phone is required; both may be provided.
      properties:
        email:
          type: string
          format: email
          description: Email of the new user.
        phone:
          type: string
          description: Phone number of the new user (E.164).
        user_metadata:
          type: object
          additionalProperties: true
          description: Arbitrary metadata defined in the app's user metadata schema.
    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        phone:
          type: string
        user_metadata:
          type: object
          additionalProperties: true
    CreateMagicLinkRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        phone:
          type: string
        user_id:
          type: string
          description: Target an existing user by ID instead of an identifier.
        channel:
          type: string
          enum: [email, phone]
          description: Delivery channel. Required if send is true.
        send:
          type: boolean
          description: Whether Passage should deliver the magic link.
        language:
          type: string
          description: Language of the email or SMS to send.
        magic_link_path:
          type: string
          description: Relative URL the magic link points to.
        redirect_url:
          type: string
        ttl:
          type: integer
          description: Time to live, in minutes.
        type:
          type: string
          enum: [login, verify_identifier]
          description: Defaults to login.
    MagicLinkResponse:
      type: object
      properties:
        magic_link:
          $ref: '#/components/schemas/MagicLink'
    MagicLink:
      type: object
      properties:
        id:
          type: string
        app_id:
          type: string
        user_id:
          type: string
        identifier:
          type: string
        type:
          type: string
          enum: [login, verify_identifier]
        redirect_url:
          type: string
        ttl:
          type: integer
        url:
          type: string
        secret:
          type: string
        activated:
          type: boolean
    UserResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        email_verified:
          type: boolean
        phone:
          type: string
        phone_verified:
          type: boolean
        external_id:
          type: string
          description: Only set if the user was created in a Flex app.
        status:
          type: string
          enum: [active, inactive, pending]
        login_count:
          type: integer
        webauthn:
          type: boolean
        webauthn_types:
          type: array
          items:
            type: string
        webauthn_devices:
          type: array
          items:
            $ref: '#/components/schemas/WebAuthnDevice'
        user_metadata:
          type: object
          additionalProperties: true
        last_login_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    WebAuthnDevice:
      type: object
      properties:
        id:
          type: string
        cred_id:
          type: string
        friendly_name:
          type: string
        type:
          type: string
        last_login_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ListDevicesResponse:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/WebAuthnDevice'
    ListPaginatedUsersResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserListItem'
        page:
          type: integer
        limit:
          type: integer
        created_before:
          type: integer
          format: int64
        total_users:
          type: integer
          format: int64
        _links:
          type: object
          additionalProperties: true
    UserListItem:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        email_verified:
          type: boolean
        phone:
          type: string
        phone_verified:
          type: boolean
        external_id:
          type: string
        status:
          type: string
          enum: [active, inactive, pending]
        login_count:
          type: integer
        user_metadata:
          type: object
          additionalProperties: true
        last_login_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time