Box Users API
The Box Users API provides endpoints for creating, retrieving, updating, and deleting user accounts, including managed users and app users, as well as listing enterprise users and managing user settings.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Users API
description: Needs a description.
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.
* `all` returns every kind of user for whom the
`login` or `name` partially matches the
`filter_term`. It will only return an external user
if the login matches the `filter_term` completely,
and in that case it will only return that user.
* `managed` returns all managed and app users for whom
the `login` or `name` partially matches the
`filter_term`.
* `external` returns all external users for whom the
`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: [email protected]
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/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:
- [email protected]
- [email protected]
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
not valid.
* `Users can not be NULL or EMPTY` when no value is provided
* `User id format is string` when the provided user id format
is incorrect
* `Supported payload format is JSON` when the provided payload
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}:
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:
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: [email protected]
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: [email protected]
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
not valid.
* `invalid_parameter` when a parameter is formatted incorrectly,
for example when the `notification_email` has an incorrectly formatted
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.
* `access_denied_insufficient_permissions` when the user does not
have
the right permissions, for example when updating the notification email
is turned off for the enterprise.
* `denied_by_policy` when the user does not have the right
permissions
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}/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
response.
content:
image/jpg:
schema:
type: string
format: binary
description: The avatar
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_users_id_avatar
x-box-tag: avatars
summary: Box Add or update user avatar
tags:
- Users
description: Adds or updates a user avatar.
parameters:
- name: user_id
description: The ID of the user.
example: '12345'
in: path
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- pic
properties:
pic:
type: string
format: binary
description: |-
The image file to be uploaded to Box.
Accepted file extensions are `.jpg` or `.png`.
The maximum file size is 1MB.
responses:
'200':
description: |-
* `ok`: Returns the `pic_urls` object with URLs to existing
user avatars that were updated.
content:
application/json:
schema:
$ref: '#/components/schemas/UserAvatar'
'201':
description: |-
* `created`: Returns the `pic_urls` object with URLS to user avatars
uploaded to Box with the request.
content:
application/json:
schema:
$ref: '#/components/schemas/UserAvatar'
'400':
description: |-
* `bad_request`: Returns an error when:
* An image is not included in the request
* The uploaded file is empty
* The image size exceeds 1024 * 1024 pixels
or 1MB
* The file extension is other than `.jpg` or `.png`.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'403':
description: >-
* `forbidden`: Returns an error if the user does not have
permissions
necessary to upload an avatar or is not activated.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
* `not_found`: Returns an error if the user
does not exist or cannot be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/users-openapi-original.yml