openapi: 3.0.1
info:
  title: Passage by 1Password Management Devices Users 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.
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'
components:
  schemas:
    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        phone:
          type: string
        user_metadata:
          type: object
          additionalProperties: true
    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
    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
    UserResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
    Error:
      type: object
      properties:
        code:
          type: string
        error:
          type: string
        message:
          type: string
    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
    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.
    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
  parameters:
    UserID:
      name: user_id
      in: path
      required: true
      description: The Passage user ID.
      schema:
        type: string
    AppID:
      name: app_id
      in: path
      required: true
      description: The Passage application ID.
      schema:
        type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Passage Management API key, sent as: Authorization: Bearer <PASSAGE_API_KEY>'