Box Groups API

openapi: 3.2.0
info:
  title: Box Groups API
  x-refined-note:
  - x-box-commit-hash differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Groups across 3 of this provider''s published API definitions: box-openapi-original.yml, collaborations-openapi-original.yml, groups-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server
tags:
- name: Groups
  description: Groups created in an enterprise.
  x-box-tag: groups
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'
      security:
      - OAuth2Security: []
    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.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n  group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n  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'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
  /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'
      security:
      - OAuth2Security: []
    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.\n\n* `admins_only` - the enterprise admin, co-admins, group's\n  group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n  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'
      security:
      - OAuth2Security: []
    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'
      security:
      - OAuth2Security: []
    servers:
    - url: https://api.box.com/2.0
      description: Box Platform API server
  /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_2'
  /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_3'
        '403':
          description: Returns an error if there are insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError_3'
        '404':
          description: Returns an error if the resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError_3'
        '429':
          description: Returns an error if the request limit is exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError_3'
        '500':
          description: Returns an error if there is an internal server issue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError_3'
        '503':
          description: Returns an error if the request timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError_3'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError_3'
  /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_3'
components:
  schemas:
    Group:
      title: Group
      type: object
      x-box-resource-id: group
      x-box-variant: standard
      description: 'A standard representation of a group, as returned from any

        group API endpoints by default'
      allOf:
      - $ref: '#/components/schemas/Group--Mini'
      - properties:
          created_at:
            type: string
            format: date-time
            description: When the group object was created
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: When the group object was last modified
            example: '2012-12-12T10:53:43-08:00'
    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
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
        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
        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
          - 'null'
          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
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
    Group--Base:
      title: Group (Base)
      type: object
      x-box-resource-id: group--base
      x-box-sanitized: true
      x-box-tag: groups
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: A base representation of a group.
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier for this object
          example: '11446498'
        type:
          type: string
          description: '`group`'
          example: group
          enum:
          - group
    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\n(Get Memberships for Group).\n\n* `admins_only` - the enterprise admin, co-admins, group's\n  group admin\n* `admins_and_members` - all admins and group members\n* `all_managed_users` - all managed users in the\n  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.'
    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'
    Group--Mini:
      title: Group (Mini)
      type: object
      x-box-resource-id: group--mini
      x-box-variant: mini
      description: 'Mini representation of a group, including id and name of

        group.'
      allOf:
      - $ref: '#/components/schemas/Group--Base'
      - properties:
          name:
            type: string
            description: The name of the group
            example: Support
          group_type:
            type: string
            description: The type of the group.
            example: managed_group
            enum:
            - managed_group
            - all_users_group
    ClientError_2:
      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
          - unauthorize

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-groups-api-openapi.yml