openapi: 3.1.0
info:
  title: 1Password API
  description: Manage users within 1Password accounts.
  version: v1beta1
paths:
  /v1beta1/accounts/{account}/users:
    get:
      summary: ListUsers
      description: List users in an account.
      operationId: ListUsers
      parameters:
        - name: account
          in: path
          description: The account id.
          required: true
          schema:
            type: string
        - name: filter
          in: query
          description: |-
            Filter value: "user.isActive()" or "user.isSuspended()".
             Omit or leave empty for both. Invalid values result in InvalidArgument.
          required: false
          schema:
            type: string
            title: filter
            description: |-
              (OPTIONAL) Filter value: "user.isActive()" or "user.isSuspended()".
               Omit or leave empty for both. Invalid values result in InvalidArgument.
        - name: max_page_size
          in: query
          description: The maximum number of users to return per page.
          required: false
          schema:
            type: integer
            title: max_page_size
            format: int32
            description: (OPTIONAL) The maximum number of users to return per page.
        - name: page_token
          in: query
          description: A page token from a previous ListUsers call.
          required: false
          schema:
            type: string
            title: page_token
            description: (OPTIONAL) A page token from a previous ListUsers call.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user.v1beta1.ListUsersResponse'
        "401":
          description: Unauthenticated.
        "403":
          description: Permission denied.
        "404":
          description: Not found.
        "500":
          description: Internal server error.
  /v1beta1/accounts/{account}/users/{user}:
    get:
      summary: GetUser
      description: Get a user by ID.
      operationId: GetUser
      parameters:
        - name: account
          in: path
          description: The account id.
          required: true
          schema:
            type: string
        - name: user
          in: path
          description: The user id.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user.v1beta1.User'
        "401":
          description: Unauthenticated.
        "403":
          description: Permission denied.
        "404":
          description: Not found.
        "500":
          description: Internal server error.
  /v1beta1/accounts/{account}/users/{user}:reactivate:
    post:
      summary: Re-activate a suspended user.
      description: |-
        Transitions the user's state from SUSPENDED to ACTIVE.
         Returns FAILED_PRECONDITION if the user is not in the SUSPENDED state.
      operationId: :ReactivateUser
      parameters:
        - name: account
          in: path
          description: The account id.
          required: true
          schema:
            type: string
        - name: user
          in: path
          description: The user id.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user.v1beta1.User'
        "401":
          description: Unauthenticated.
        "403":
          description: Permission denied.
        "404":
          description: Not found.
        "500":
          description: Internal server error.
  /v1beta1/accounts/{account}/users/{user}:suspend:
    post:
      summary: Suspend a user.
      description: |-
        Transitions the user's state from ACTIVE to SUSPENDED.
         Returns FAILED_PRECONDITION if the user is not in the ACTIVE state.
      operationId: :SuspendUser
      parameters:
        - name: account
          in: path
          description: The account id.
          required: true
          schema:
            type: string
        - name: user
          in: path
          description: The user id.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user.v1beta1.User'
        "401":
          description: Unauthenticated.
        "403":
          description: Permission denied.
        "404":
          description: Not found.
        "500":
          description: Internal server error.
components:
  schemas:
    user.v1beta1.ListUsersResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/user.v1beta1.User'
          title: results
          description: The list of users.
        next_page_token:
          type: string
          title: next_page_token
          description: A token to retrieve the next page of results.
      title: ListUsersResponse
      additionalProperties: false
      description: Response message for listing users.
    user.v1beta1.User:
      type: object
      properties:
        id:
          type: string
          title: id
          description: The unique identifier of the user.
          readOnly: true
        email:
          type: string
          title: email
          description: The email address of the user.
          readOnly: true
        display_name:
          type: string
          title: display_name
          description: The display name of the user.
          readOnly: true
        state:
          title: state
          description: The current state of the user.
          readOnly: true
          $ref: '#/components/schemas/user.v1beta1.User.State'
        create_time:
          title: create_time
          description: The time the user was created.
          readOnly: true
          type: string
          format: date-time
        path:
          type: string
          title: path
          description: |-
            The resource path of the user.
             Format: accounts/{account_id}/users/{user_id}
          readOnly: true
      title: User
      additionalProperties: false
      description: A user within an account.
      x-aep-resource:
        singular: user
    user.v1beta1.User.State:
      type: string
      title: State
      enum:
        - STATE_UNSPECIFIED
        - ACTIVE
        - SUSPENDED
      description: |-
        The state of a user.
         Additional states may be added in the future.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
security:
  - BearerAuth: []
