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