Box Group Memberships API
The Box Group Memberships API manages the relationship between users and groups, allowing applications to add users to groups, retrieve membership details, update roles, and remove members.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Group Memberships API
description: Needs a description.
paths:
/group_memberships:
post:
operationId: post_group_memberships
summary: Box Add user to group
tags:
- Group Memberships
x-box-tag: memberships
description: |-
Creates a group membership. Only users with
admin-level permissions will be able to use this API.
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:
- user
- group
properties:
user:
type: object
description: The user to add to the group.
required:
- id
properties:
id:
type: string
description: The ID of the user to add to the group
example: '1434325'
group:
type: object
description: The group to add the user to.
required:
- id
properties:
id:
type: string
description: The ID of the group to add the user to
example: '4545523'
role:
type: string
example: member
description: The role of the user in the group.
enum:
- member
- admin
configurable_permissions:
type: object
example:
can_run_reports: true
description: >-
Custom configuration for the permissions an admin
if a group will receive. This option has no effect
on members with a role of `member`.
Setting these permissions overwrites the default
access levels of an admin.
Specifying a value of "null" for this object will disable
all configurable permissions. Specifying permissions will
set
them accordingly, omitted permissions will be enabled by
default.
additionalProperties:
type: boolean
description: A key value pair of custom permissions.
example: true
x-box-example-key: can_run_reports
responses:
'201':
description: Returns a new group membership object.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMembership'
'403':
description: |-
Returns an error when the user cannot be added
to a group.
* `forbidden_by_policy`: Adding a user
to a group 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'
/group_memberships/{group_membership_id}:
get:
operationId: get_group_memberships_id
summary: Box Get group membership
tags:
- Group Memberships
x-box-tag: memberships
description: |-
Retrieves a specific group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
parameters:
- name: group_membership_id
description: The ID of the group membership.
example: '434534'
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 membership object.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMembership'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
put:
operationId: put_group_memberships_id
summary: Box Update group membership
tags:
- Group Memberships
x-box-tag: memberships
description: |-
Updates a user's group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
parameters:
- name: group_membership_id
description: The ID of the group membership.
example: '434534'
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:
role:
type: string
example: member
description: The role of the user in the group.
enum:
- member
- admin
configurable_permissions:
type: object
example:
can_run_reports: true
description: >-
Custom configuration for the permissions an admin
if a group will receive. This option has no effect
on members with a role of `member`.
Setting these permissions overwrites the default
access levels of an admin.
Specifying a value of "null" for this object will disable
all configurable permissions. Specifying permissions will
set
them accordingly, omitted permissions will be enabled by
default.
additionalProperties:
type: boolean
description: A key value pair of custom permissions.
example: true
x-box-example-key: can_run_reports
responses:
'200':
description: Returns a new group membership object.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupMembership'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
delete:
operationId: delete_group_memberships_id
summary: Box Remove user from group
tags:
- Group Memberships
x-box-tag: memberships
description: |-
Deletes a specific group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
parameters:
- name: group_membership_id
description: The ID of the group membership.
example: '434534'
in: path
required: true
schema:
type: string
responses:
'204':
description: |-
A blank response is returned if the membership was
successfully deleted.
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
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
GroupMembership:
title: Group membership
type: object
x-box-resource-id: group_membership
x-box-tag: memberships
description: |-
Membership is used to signify that a user is part of a
group.
properties:
id:
type: string
description: The unique identifier for this group membership
example: '11446498'
type:
type: string
description: '`group_membership`'
example: group_membership
enum:
- group_membership
user:
allOf:
- $ref: '#/components/schemas/User--Mini'
- description: The user that the membership applies to
group:
allOf:
- $ref: '#/components/schemas/Group--Mini'
- description: The group that the membership applies to
role:
type: string
example: member
description: The role of the user in the group.
enum:
- member
- admin
created_at:
type: string
format: date-time
description: The time this membership was created.
example: '2012-12-12T10:53:43-08:00'
modified_at:
type: string
format: date-time
description: The time this membership was last modified.
example: '2012-12-12T10:53:43-08:00'
tags:
- name: Group Memberships