Box Groups API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Groups API
  description: Needs a description.
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'
    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'
  /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.\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'
    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}/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'
  /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}/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'
components:
  schemas:
    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'
    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:
      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'
    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
    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.'
    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'
    Collaboration:
      title: Collaboration
      type: object
      x-box-resource-id: collaboration
      x-box-tag: user_collaborations
      description: 'Collaborations define access permissions for users and groups to files and

        folders, similar to access control lists. A collaboration object grants a

        user or group access to a file or folder with permissions defined by a

        specific role.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: The unique identifier for this collaboration.
          example: '12345678'
        type:
          type: string
          description: '`collaboration`'
          example: collaboration
          enum:
          - collaboration
        item:
          allOf:
          - oneOf:
            - $ref: '#/components/schemas/File'
            - $ref: '#/components/schemas/Folder'
            - $ref: '#/components/schemas/WebLink'
          - description: 'The file o

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