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 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 group memberships items: $ref: '#/components/schemas/GroupMembership' Collaborations: title: Collaborations type: object x-box-resource-id: collaborations x-box-tag: user_collaborations description: A list of collaborations 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 collaborations items: $ref: '#/components/schemas/Collaboration' tags: - name: Groups