Box Groups API
The Box Groups API provides endpoints for creating, listing, retrieving, updating, and deleting groups within an enterprise, enabling organized management of user permissions and collaboration access.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Groups API
description: Needs a description.
paths:
/groups:
get:
operationId: get_groups
summary: Box List groups for enterprise
x-box-tag: groups
tags:
- Groups
description: |-
Retrieves all of the groups for a given enterprise. The user
must have admin permissions to inspect enterprise's groups.
parameters:
- name: filter_term
description: |-
Limits the results to only groups whose `name` starts
with the search term.
in: query
required: false
example: Engineering
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: 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: 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
responses:
'200':
description: |-
Returns a collection of group objects. If there are no groups, an
empty collection will be returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Groups'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_groups
summary: Box Create group
tags:
- Groups
x-box-tag: groups
description: |-
Creates a new group of users in an enterprise. Only users with admin
permissions can create new groups.
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
example: Customer Support
description: >-
The name of the new group to be created. This name must be
unique
within the enterprise.
provenance:
type: string
description: |-
Keeps track of which external source this group is
coming, for example `Active Directory`, or `Okta`.
Setting this will also prevent Box admins from editing
the group name and its members directly via the Box
web application.
This is desirable for one-way syncing of groups.
maxLength: 255
example: Active Directory
external_sync_identifier:
type: string
description: |-
An arbitrary identifier that can be used by
external group sync tools to link this Box Group to
an external group.
Example values of this field
could be an **Active Directory Object ID** or a **Google
Group ID**.
We recommend you use of this field in
order to avoid issues when group names are updated in
either Box or external systems.
example: AD:123456
description:
type: string
description: A human readable description of the group.
maxLength: 255
example: '"Customer Support Group - as imported from Active Directory"'
invitability_level:
type: string
example: admins_only
description: |-
Specifies who can invite the group to collaborate
on folders.
When set to `admins_only` the enterprise admin, co-admins,
and the group's admin can invite the group.
When set to `admins_and_members` all the admins listed
above and group members can invite the group.
When set to `all_managed_users` all managed users in the
enterprise can invite the group.
enum:
- admins_only
- admins_and_members
- all_managed_users
member_viewability_level:
type: string
example: admins_only
description: |-
Specifies who can see the members of the group.
* `admins_only` - the enterprise admin, co-admins, group's
group admin
* `admins_and_members` - all admins and group members
* `all_managed_users` - all managed users in the
enterprise
enum:
- admins_only
- admins_and_members
- all_managed_users
responses:
'201':
description: Returns the new group object.
content:
application/json:
schema:
$ref: '#/components/schemas/Group--Full'
'409':
description: >-
Returns an error a conflict is stopping the group from being
created.
* `invalid_parameter`: Often returned if the group name is not
unique in
the enterprise.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/groups/terminate_sessions:
post:
operationId: post_groups_terminate_sessions
summary: Box Create jobs to terminate user group session
tags:
- Groups
x-box-tag: session_termination
description: |-
Validates the roles and permissions of the group,
and creates asynchronous jobs
to terminate the group's sessions.
Returns the status for the POST request.
requestBody:
content:
application/json:
schema:
type: object
required:
- group_ids
properties:
group_ids:
example:
- '123456'
- '456789'
type: array
description: A list of group IDs
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.
* `Groups can not be NULL or EMPTY` when no value is provided
* `group id format is string` when the provided group 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 request 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'
/groups/{group_id}:
get:
operationId: get_groups_id
summary: Box Get group
tags:
- Groups
x-box-tag: groups
description: |-
Retrieves information about a group. Only members of this
group or users with admin-level permissions will be able to
use this API.
parameters:
- name: group_id
description: The ID of the group.
example: '57645'
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 the group object
content:
application/json:
schema:
$ref: '#/components/schemas/Group--Full'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_groups_id
summary: Box Update group
tags:
- Groups
x-box-tag: groups
description: |-
Updates a specific group. Only admins of this
group or users with admin-level permissions will be able to
use this API.
parameters:
- name: group_id
description: The ID of the group.
example: '57645'
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:
name:
type: string
example: Customer Support
description: >-
The name of the new group to be created. Must be unique
within the
enterprise.
provenance:
type: string
description: |-
Keeps track of which external source this group is
coming, for example `Active Directory`, or `Okta`.
Setting this will also prevent Box admins from editing
the group name and its members directly via the Box
web application.
This is desirable for one-way syncing of groups.
maxLength: 255
example: Active Directory
external_sync_identifier:
type: string
description: |-
An arbitrary identifier that can be used by
external group sync tools to link this Box Group to
an external group.
Example values of this field
could be an **Active Directory Object ID** or a **Google
Group ID**.
We recommend you use of this field in
order to avoid issues when group names are updated in
either Box or external systems.
example: AD:123456
description:
type: string
description: A human readable description of the group.
maxLength: 255
example: '"Customer Support Group - as imported from Active Directory"'
invitability_level:
type: string
example: admins_only
description: |-
Specifies who can invite the group to collaborate
on folders.
When set to `admins_only` the enterprise admin, co-admins,
and the group's admin can invite the group.
When set to `admins_and_members` all the admins listed
above and group members can invite the group.
When set to `all_managed_users` all managed users in the
enterprise can invite the group.
enum:
- admins_only
- admins_and_members
- all_managed_users
member_viewability_level:
type: string
example: admins_only
description: |-
Specifies who can see the members of the group.
* `admins_only` - the enterprise admin, co-admins, group's
group admin
* `admins_and_members` - all admins and group members
* `all_managed_users` - all managed users in the
enterprise
enum:
- admins_only
- admins_and_members
- all_managed_users
responses:
'200':
description: Returns the updated group object.
content:
application/json:
schema:
$ref: '#/components/schemas/Group--Full'
'409':
description: >-
Returns an error a conflict is stopping the group from being
created.
* `invalid_parameter`: Often returned if the group name is not
unique in
the enterprise.
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_groups_id
summary: Box Remove group
tags:
- Groups
x-box-tag: groups
description: |-
Permanently deletes a group. Only users with
admin-level permissions will be able to use this API.
parameters:
- name: group_id
description: The ID of the group.
example: '57645'
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
A blank response is returned if the group was
successfully deleted.
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/groups/{group_id}/memberships:
get:
operationId: get_groups_id_memberships
summary: Box List members of group
x-box-tag: memberships
tags:
- Groups
description: |-
Retrieves all the members for a group. Only members of this
group or users with admin-level permissions will be able to
use this API.
parameters:
- name: group_id
description: The ID of the group.
example: '57645'
in: path
required: true
schema:
type: string
- 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: 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
responses:
'200':
description: |-
Returns a collection of membership objects. If there are no
memberships, an empty collection will be returned.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMemberships'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/groups/{group_id}/collaborations:
get:
operationId: get_groups_id_collaborations
summary: Box List group collaborations
x-box-tag: list_collaborations
tags:
- Groups
description: |-
Retrieves all the collaborations for a group. The user
must have admin permissions to inspect enterprise's groups.
Each collaboration object has details on which files or
folders the group has access to and with what role.
parameters:
- name: group_id
description: The ID of the group.
example: '57645'
in: path
required: true
schema:
type: string
- 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: 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
responses:
'200':
description: |-
Returns a collection of collaboration objects. If there are no
collaborations, an empty collection will be returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Collaborations'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
Groups:
title: Groups
type: object
x-box-resource-id: groups
x-box-tag: groups
description: A list of groups.
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
type: integer
format: int64
order:
description: >-
The order by which items are returned.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
type: array
items:
type: object
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
type: string
description: The direction to order by, either ascending or descending
example: ASC
enum:
- ASC
- DESC
- properties:
entries:
type: array
description: A list of groups
items:
$ref: '#/components/schemas/Group--Full'
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
message:
description: A short message describing the error.
example: Method Not Allowed
type: string
nullable: false
context_info:
description: |-
A free-form object that contains additional context
about the error. The possible fields are defined on
a per-endpoint basis. `message` is only one example.
type: object
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
help_url:
description: A URL that links to more information about why this error occurred.
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
type: string
nullable: false
request_id:
description: |-
A unique identifier for this response, which can be used
when contacting Box support.
type: string
example: abcdef123456
nullable: false
Group--Full:
title: Group (Full)
type: object
x-box-resource-id: group--full
x-box-variant: full
description: |-
Groups contain a set of users, and can be used in place of
users in some operations, such as collaborations.
allOf:
- $ref: '#/components/schemas/Group'
- properties:
provenance:
type: string
description: |-
Keeps track of which external source this group is
coming from (e.g. "Active Directory", "Google Groups",
"Facebook Groups"). Setting this will
also prevent Box users from editing the group name
and its members directly via the Box web application.
This is desirable for one-way syncing of groups.
maxLength: 255
example: Active Directory
external_sync_identifier:
type: string
description: |-
An arbitrary identifier that can be used by
external group sync tools to link this Box Group to
an external group. Example values of this field
could be an Active Directory Object ID or a Google
Group ID. We recommend you use of this field in
order to avoid issues when group names are updated in
either Box or external systems.
example: AD:123456
description:
type: string
description: Human readable description of the group.
maxLength: 255
example: Support Group - as imported from Active Directory
invitability_level:
type: string
example: admins_only
description: |-
Specifies who can invite the group to collaborate
on items.
When set to `admins_only` the enterprise admin, co-admins,
and the group's admin can invite the group.
When set to `admins_and_members` all the admins listed
above and group members can invite the group.
When set to `all_managed_users` all managed users in the
enterprise can invite the group.
enum:
- admins_only
- admins_and_members
- all_managed_users
member_viewability_level:
type: string
example: admins_only
description: |-
Specifies who can view the members of the group
(Get Memberships for Group).
* `admins_only` - the enterprise admin, co-admins, group's
group admin
* `admins_and_members` - all admins and group members
* `all_managed_users` - all managed users in the
enterprise
enum:
- admins_only
- admins_and_members
- all_managed_users
permissions:
allOf:
- type: object
description: The permissions that the authenticated user has for a group.
properties:
can_invite_as_collaborator:
type: boolean
description: >-
Specifies if the user can invite the group to
collaborate on any items.
example: true
- description: |-
Describes the permissions that the current user has
for this group.
GroupMemberships:
title: Group memberships
type: object
x-box-resource-id: group_memberships
x-box-tag: memberships
description: A list of group memberships.
allOf:
- type: object
description: The part of an API response that describes pagination
properties:
total_count:
description: >-
One greater than the offset of the last entry in the entire
collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
type: integer
format: int64
limit:
description: >-
The limit that was used for these entries. This will be the same
as the
`limit` query parameter unless that value exceeded the maximum
value
allowed. The maximum value varies by API.
example: 1000
type: integer
format: int64
offset:
description: >-
The 0-based offset of the first entry in this set. This will be
the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based
pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/groups-openapi-original.yml