Box Group Memberships API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Group Memberships API
  description: Needs a description.
tags:
- name: Group Memberships
  description: 'Group memberships signify that

    a user is a part of the group.'
  x-box-tag: memberships
paths:
  /users/{user_id}/memberships:
    get:
      operationId: get_users_id_memberships
      summary: Box List user's groups
      x-box-tag: memberships
      tags:
      - Group Memberships
      description: 'Retrieves all the groups for a user. Only members of this

        group or users with admin-level permissions will be able to

        use this API.'
      parameters:
      - name: user_id
        description: The ID of the user.
        example: '12345'
        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}/memberships:
    get:
      operationId: get_groups_id_memberships
      summary: Box List members of group
      x-box-tag: memberships
      tags:
      - Group Memberships
      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'
  /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:
    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
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    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
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            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'
    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