Box Users API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Users API
  description: Needs a description.
tags:
- name: Users
  description: 'Box API supports a variety of users,

    ranging from real employees

    logging in with their Managed User account,

    to applications using App Users to drive powerful

    automation workflows.'
  x-box-tag: users
paths:
  /users:
    get:
      operationId: get_users
      x-box-tag: users
      summary: Box List enterprise users
      tags:
      - Users
      description: 'Returns a list of all users for the Enterprise along with their `user_id`,

        `public_name`, and `login`.


        The application and the authenticated user need to

        have the permission to look up users in the entire

        enterprise.'
      parameters:
      - name: filter_term
        description: 'Limits the results to only users who''s `name` or

          `login` start with the search term.


          For externally managed users, the search term needs

          to completely match the in order to find the user, and

          it will only return one user at a time.'
        in: query
        required: false
        example: john
        schema:
          type: string
      - name: user_type
        description: "Limits the results to the kind of user specified.\n\n* `all` returns every kind of user for whom the\n  `login` or `name` partially matches the\n  `filter_term`. It will only return an external user\n  if the login matches the `filter_term` completely,\n  and in that case it will only return that user.\n* `managed` returns all managed and app users for whom\n  the `login` or `name` partially matches the\n  `filter_term`.\n* `external` returns all external users for whom the\n  `login` matches the `filter_term` exactly."
        in: query
        required: false
        example: managed
        schema:
          type: string
          enum:
          - all
          - managed
          - external
      - name: external_app_user_id
        in: query
        required: false
        schema:
          type: string
        example: my-user-1234
        description: 'Limits the results to app users with the given

          `external_app_user_id` value.


          When creating an app user, an

          `external_app_user_id` value can be set. This value can

          then be used in this endpoint to find any users that

          match that `external_app_user_id` value.'
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: offset
        description: 'The offset of the item at which to begin the response.


          Queries with offset parameter value

          exceeding 10000 will be rejected

          with a 400 response.'
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          default: 0
      - name: limit
        description: The maximum number of items to return per page.
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          maximum: 1000
      - name: usemarker
        description: 'Specifies whether to use marker-based pagination instead of

          offset-based pagination. Only one pagination method can

          be used at a time.


          By setting this value to true, the API will return a `marker` field

          that can be passed as a parameter to this endpoint to get the next

          page of the response.'
        in: query
        required: false
        example: true
        schema:
          type: boolean
      - name: marker
        description: 'Defines the position marker at which to begin returning results. This is

          used when paginating using marker-based pagination.


          This requires `usemarker` to be set to `true`.'
        in: query
        required: false
        example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
        schema:
          type: string
      responses:
        '200':
          description: Returns all of the users in the enterprise.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_users
      summary: Box Create user
      tags:
      - Users
      x-box-tag: users
      description: 'Creates a new managed user in an enterprise. This endpoint

        is only available to users and applications with the right

        admin permissions.'
      parameters:
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the user
                  example: Aaron Levie
                  maxLength: 50
                login:
                  type: string
                  description: 'The email address the user uses to log in


                    Required, unless `is_platform_access_only`

                    is set to `true`.'
                  example: boss@box.com
                is_platform_access_only:
                  type: boolean
                  example: true
                  description: Specifies that the user is an app user.
                role:
                  type: string
                  enum:
                  - coadmin
                  - user
                  description: The user’s enterprise role
                  example: user
                language:
                  type: string
                  description: 'The language of the user, formatted in modified version of the

                    [ISO 639-1](/guides/api-calls/language-codes) format.'
                  example: en
                is_sync_enabled:
                  type: boolean
                  description: Whether the user can use Box Sync
                  example: true
                job_title:
                  type: string
                  description: The user’s job title
                  maxLength: 100
                  example: CEO
                phone:
                  type: string
                  description: The user’s phone number
                  maxLength: 100
                  example: '6509241374'
                address:
                  type: string
                  description: The user’s address
                  maxLength: 255
                  example: 900 Jefferson Ave, Redwood City, CA 94063
                space_amount:
                  type: integer
                  format: int64
                  description: 'The user’s total available space in bytes. Set this to `-1` to

                    indicate unlimited storage.'
                  example: 11345156112
                tracking_codes:
                  type: array
                  items:
                    $ref: '#/components/schemas/TrackingCode'
                  description: 'Tracking codes allow an admin to generate reports from the

                    admin console and assign an attribute to a specific group

                    of users. This setting must be enabled for an enterprise before it

                    can be used.'
                can_see_managed_users:
                  type: boolean
                  example: true
                  description: 'Whether the user can see other enterprise users in their

                    contact list'
                timezone:
                  type: string
                  format: timezone
                  description: The user's timezone
                  example: Africa/Bujumbura
                is_external_collab_restricted:
                  type: boolean
                  example: true
                  description: 'Whether the user is allowed to collaborate with users outside

                    their enterprise'
                is_exempt_from_device_limits:
                  type: boolean
                  example: true
                  description: Whether to exempt the user from enterprise device limits
                is_exempt_from_login_verification:
                  type: boolean
                  example: true
                  description: Whether the user must use two-factor authentication
                status:
                  type: string
                  enum:
                  - active
                  - inactive
                  - cannot_delete_edit
                  - cannot_delete_edit_upload
                  description: The user's account status
                  example: active
                external_app_user_id:
                  type: string
                  example: my-user-1234
                  description: 'An external identifier for an app user, which can be used to look

                    up the user. This can be used to tie user IDs from external

                    identity providers to Box users.'
      responses:
        '201':
          description: Returns a user object for the newly created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User--Full'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /users/me:
    get:
      operationId: get_users_me
      x-box-tag: users
      summary: Box Get current user
      tags:
      - Users
      description: 'Retrieves information about the user who is currently authenticated.


        In the case of a client-side authenticated OAuth 2.0 application

        this will be the user who authorized the app.


        In the case of a JWT, server-side authenticated application

        this will be the service account that belongs to the application

        by default.


        Use the `As-User` header to change who this API call is made on behalf of.'
      parameters:
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Returns a single user object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User--Full'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /users/{user_id}:
    get:
      operationId: get_users_id
      x-box-tag: users
      summary: Box Get user
      tags:
      - Users
      description: 'Retrieves information about a user in the enterprise.


        The application and the authenticated user need to

        have the permission to look up users in the entire

        enterprise.


        This endpoint also returns a limited set of information

        for external users who are collaborated on content

        owned by the enterprise for authenticated users with the

        right scopes. In this case, disallowed fields will return

        null instead.'
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: 'Returns a single user object.


            Not all available fields are returned by default. Use the

            [fields](#param-fields) query parameter to explicitly request

            any specific fields using the [fields](#get-users-id--request--fields)

            parameter.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User--Full'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_users_id
      summary: Box Update user
      tags:
      - Users
      x-box-tag: users
      x-box-enable-explorer: true
      description: 'Updates a managed or app user in an enterprise. This endpoint

        is only available to users and applications with the right

        admin permissions.'
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                enterprise:
                  type: string
                  nullable: true
                  example: null
                  description: 'Set this to `null` to roll the user out of the enterprise

                    and make them a free user'
                notify:
                  type: boolean
                  example: true
                  description: 'Whether the user should receive an email when they

                    are rolled out of an enterprise'
                name:
                  type: string
                  description: The name of the user
                  example: Aaron Levie
                  maxLength: 50
                login:
                  type: string
                  description: 'The email address the user uses to log in


                    Note: If the target user''s email is not confirmed, then the

                    primary login address cannot be changed.'
                  example: somename@box.com
                role:
                  type: string
                  enum:
                  - coadmin
                  - user
                  description: The user’s enterprise role
                  example: user
                language:
                  type: string
                  description: 'The language of the user, formatted in modified version of the

                    [ISO 639-1](/guides/api-calls/language-codes) format.'
                  example: en
                is_sync_enabled:
                  type: boolean
                  description: Whether the user can use Box Sync
                  example: true
                job_title:
                  type: string
                  description: The user’s job title
                  maxLength: 100
                  example: CEO
                phone:
                  type: string
                  description: The user’s phone number
                  maxLength: 100
                  example: '6509241374'
                address:
                  type: string
                  description: The user’s address
                  maxLength: 255
                  example: 900 Jefferson Ave, Redwood City, CA 94063
                tracking_codes:
                  type: array
                  items:
                    $ref: '#/components/schemas/TrackingCode'
                  description: 'Tracking codes allow an admin to generate reports from the

                    admin console and assign an attribute to a specific group

                    of users. This setting must be enabled for an enterprise before it

                    can be used.'
                can_see_managed_users:
                  type: boolean
                  example: true
                  description: 'Whether the user can see other enterprise users in their

                    contact list'
                timezone:
                  type: string
                  format: timezone
                  description: The user's timezone
                  example: Africa/Bujumbura
                is_external_collab_restricted:
                  type: boolean
                  example: true
                  description: 'Whether the user is allowed to collaborate with users outside

                    their enterprise'
                is_exempt_from_device_limits:
                  type: boolean
                  example: true
                  description: Whether to exempt the user from enterprise device limits
                is_exempt_from_login_verification:
                  type: boolean
                  example: true
                  description: Whether the user must use two-factor authentication
                is_password_reset_required:
                  type: boolean
                  example: true
                  description: Whether the user is required to reset their password
                status:
                  type: string
                  enum:
                  - active
                  - inactive
                  - cannot_delete_edit
                  - cannot_delete_edit_upload
                  description: The user's account status
                  example: active
                space_amount:
                  type: integer
                  format: int64
                  description: 'The user’s total available space in bytes. Set this to `-1` to

                    indicate unlimited storage.'
                  example: 11345156112
                notification_email:
                  type: object
                  nullable: true
                  description: 'An alternate notification email address to which email

                    notifications are sent. When it''s confirmed, this will be

                    the email address to which notifications are sent instead of

                    to the primary email address.


                    Set this value to `null` to remove the notification email.'
                  properties:
                    email:
                      type: string
                      example: notifications@example.com
                      description: The email address to send the notifications to.
                external_app_user_id:
                  type: string
                  example: my-user-1234
                  description: 'An external identifier for an app user, which can be used to look

                    up the user. This can be used to tie user IDs from external

                    identity providers to Box users.


                    Note: In order to update this field, you need to request a token

                    using the application that created the app user.'
      responses:
        '200':
          description: Returns the updated user object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User--Full'
        '400':
          description: "Returns an error if some of the parameters are missing or\nnot valid.\n\n* `invalid_parameter` when a parameter is formatted incorrectly,\n  for example when the `notification_email` has an incorrectly formatted\n  email address."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: "Returns an error if the user is not allowed to make the changes.\n\n* `access_denied_insufficient_permissions` when the user does not have\n  the right permissions, for example when updating the notification email\n  is turned off for the enterprise.\n* `denied_by_policy` when the user does not have the right permissions\n  due to the information barrier restrictions."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_users_id
      x-box-tag: users
      summary: Box Delete user
      tags:
      - Users
      description: 'Deletes a user. By default this will fail if the user

        still owns any content. Move their owned content first

        before proceeding, or use the `force` field to delete

        the user and their files.'
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: notify
        schema:
          type: boolean
        in: query
        example: true
        description: 'Whether the user will receive email notification of

          the deletion'
      - name: force
        schema:
          type: boolean
        in: query
        example: true
        description: 'Whether the user should be deleted even if this user

          still own files'
      responses:
        '204':
          description: Removes the user and returns an empty response.
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /users/{user_id}/folders/0:
    put:
      operationId: put_users_id_folders_0
      x-box-tag: transfer
      summary: Box Transfer owned folders
      tags:
      - Users
      description: 'Move all of the items (files, folders and workflows) owned by a user into

        another user''s account


        Only the root folder (`0`) can be transferred.


        Folders can only be moved across users by users with administrative

        permissions.


        All existing shared links and folder-level collaborations are transferred

        during the operation. Please note that while collaborations at the individual

        file-level are transferred during the operation, the collaborations are

        deleted when the original user is deleted.


        This call will be performed synchronously which might lead to a slow response

        when the source user has a large number of items in all of its folders.


        If the destination path has a metadata cascade policy attached to any of

        the parent folders, a metadata cascade operation will be kicked off

        asynchronously.


        There is currently no way to check for when this operation is finished.


        The destination folder''s name will be in the format `{User}''s Files and

        Folders`, where `{User}` is the display name of the user.


        To make this API call your application will need to have the "Read and write

        all files and folders stored in Box" scope enabled.


        Please make sure the destination user has access to `Relay` or `Relay Lite`,

        and has access to the files and folders involved in the workflows being

        transferred.


        Admins will receive an email when the operation is completed.'
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        description: 'A comma-separated list of attributes to include in the

          response. This can be used to request fields that are

          not normally returned in a standard response.


          Be aware that specifying this parameter will have the

          effect that none of the standard fields are returned in

          the response unless explicitly specified, instead only

          fields for the mini representation are returned, additional

          to the fields requested.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: notify
        description: 'Determines if users should receive email notification

          for the action performed.'
        in: query
        required: false
        example: true
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - owned_by
              properties:
                owned_by:
                  type: object
                  description: The user who the folder will be transferred to
                  required:
                  - id
                  properties:
                    id:
                      type: string
                      example: '1232234'
                      description: 'The ID of the user who the folder will be

                        transferred to'
      responses:
        '200':
          description: 'Returns the information for the newly created

            destination folder.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder--Full'
        '403':
          description: "Returns an error when folder ownership cannot be\ntransferred to another user.\n\n* `forbidden_by_policy`: Returned if ownership transfer\n is forbidden due to information barrier restrictions."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /users/terminate_sessions:
    post:
      operationId: post_users_terminate_sessions
      summary: Box Create jobs to terminate users session
      tags:
      - Users
      x-box-tag: session_termination
      description: 'Validates the roles and permissions of the user,

        and creates asynchronous jobs

        to terminate the user''s sessions.

        Returns the status for the POST request.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - user_ids
              - user_logins
              properties:
                user_ids:
                  example:
                  - '123456'
                  - '456789'
                  type: array
                  description: A list of user IDs
                  items:
                    type: string
                user_logins:
                  example:
                  - user@sample.com
                  - user2@sample.com
                  type: array
                  description: A list of user logins
                  items:
                    type: string
      responses:
        '202':
          description: Returns a message about the request status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionTerminationMessage'
        '400':
          description: "Returns an error if some of the parameters are\n not valid.\n\n * `Users can not be NULL or EMPTY` when no value is provided\n * `User id format is string` when the provided user id format\n is incorrect\n * `Supported payload format is JSON` when the provided payload\n format is incorrect"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: Returns an error if there are insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns an error if the resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '429':
          description: Returns an error if the rate limit is exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: Returns an error if there is an internal server issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '503':
          description: Returns an error if the request timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /users/{user_id}/avatar:
    get:
      operationId: get_users_id_avatar
      x-box-tag: avatars
      summary: Box Get user avatar
      tags:
      - Users
      description: Retrieves an image of a the user's avatar.
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'When an avatar can be found for the user the

            image data will be returned in the body of the

  

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-users-api-openapi.yml