> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Box Hub collaboration
> Adds a collaboration for a single user or a single group to a Box Hub.
Collaborations can be created using email address, user IDs, or group IDs.
Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
## OpenAPI
````yaml box-openapi-v2025.0.json POST /hub_collaborations
openapi: 3.0.2
info:
title: Box Platform API
description: >-
[Box Platform](https://developer.box.com) provides functionality to provide
access to content stored within [Box](https://box.com). It provides
endpoints for basic manipulation of files and folders, management of users
within an enterprise, as well as more complex topics such as legal holds and
retention policies.
termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
contact:
name: Box, Inc
url: https://developer.box.com
email: devrel@box.com
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: '2025.0'
x-box-commit-hash: 056413ec44
servers:
- url: https://api.box.com/2.0
description: Box Platform API server.
security:
- OAuth2Security: []
tags:
- name: Archives
description: A set of endpoints used to manage archives.
x-box-tag: archives
- name: Enterprise Configurations
description: >-
Enterprise configurations admins interact with to drive Box product
behavior.
x-box-tag: enterprise_configurations
- name: Box Doc Gen
description: >-
Box Doc Gen automatically generates documents from Box Doc Gen templates.
These resources represent the generation jobs and batches returned by the
Box Doc Gen endpoints, including their status and output files.
x-box-tag: docgen
- name: Box Doc Gen templates
description: Doc Gen templates are used as input to generate documents.
x-box-tag: docgen_template
- name: External Users
description: External users are collaborators from outside of your enterprise.
x-box-tag: external_users
- name: Box Hubs
description: A set of endpoints used to manage Box Hubs.
x-box-tag: hubs
- name: Box Hub Collaborations
description: A set of endpoints used to manage collaborations within a Box Hub.
x-box-tag: hub_collaborations
- name: Box Hub Document
description: >-
A set of endpoints used to retrieve Box Hub Document elements (pages and
content blocks).
x-box-tag: hub_document
- name: Box Hub Items
description: A set of endpoints used to manage items within a Box Hub.
x-box-tag: hub_items
- name: Shield lists
description: >-
Shield List allow an administrator to create a list which will be shared
between different Shield Smart Access and Threat Detection rules.
x-box-tag: shield_lists
externalDocs:
description: Box Developer Documentation.
url: https://developer.box.com
paths:
/hub_collaborations:
post:
tags:
- Box Hub Collaborations
summary: Create Box Hub collaboration
description: >-
Adds a collaboration for a single user or a single group to a Box Hub.
Collaborations can be created using email address, user IDs, or group
IDs.
operationId: post_hub_collaborations_v2025.0
parameters:
- $ref: '#/components/parameters/BoxVersionHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HubCollaborationCreateRequest'
responses:
'201':
description: Returns a new Box Hub collaboration object.
content:
application/json:
schema:
$ref: '#/components/schemas/HubCollaboration'
'403':
description: >-
Returns an error when the user does not have the right permissions
to create the collaboration.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
x-codeSamples:
- lang: curl
label: Create Box Hub collaboration
source: |-
curl -i -X POST "https://api.box.com/2.0/hub_collaborations" \
-H "box-version: 2025.0" \
-H "authorization: Bearer " \
-H "content-type: application/json" \
-d '{
"hub": {
"type": "hubs",
"id": "42037322"
},
"accessible_by": {
"type": "user",
"id": "23522323"
},
"role": "viewer"
}'
- lang: dotnet
label: Create Box Hub collaboration
source: >-
await
client.HubCollaborations.CreateHubCollaborationV2025R0Async(requestBody:
new HubCollaborationCreateRequestV2025R0(hub: new
HubCollaborationCreateRequestV2025R0HubField(id: hub.Id),
accessibleBy: new
HubCollaborationCreateRequestV2025R0AccessibleByField(type: "user")
{ Id = user.Id }, role: "viewer"));
- lang: swift
label: Create Box Hub collaboration
source: >-
try await
client.hubCollaborations.createHubCollaborationV2025R0(requestBody:
HubCollaborationCreateRequestV2025R0(hub:
HubCollaborationCreateRequestV2025R0HubField(id: hub.id),
accessibleBy:
HubCollaborationCreateRequestV2025R0AccessibleByField(type: "user",
id: user.id), role: "viewer"))
- lang: java
label: Create Box Hub collaboration
source: >-
client.getHubCollaborations().createHubCollaborationV2025R0(new
HubCollaborationCreateRequestV2025R0(new
HubCollaborationCreateRequestV2025R0HubField(hub.getId()), new
HubCollaborationCreateRequestV2025R0AccessibleByField.Builder("user").id(user.getId()).build(),
"viewer"))
- lang: node
label: Create Box Hub collaboration
source: |-
await client.hubCollaborations.createHubCollaborationV2025R0({
hub: new HubCollaborationCreateRequestV2025R0HubField({ id: hub.id }),
accessibleBy: {
type: 'user',
id: user.id,
} satisfies HubCollaborationCreateRequestV2025R0AccessibleByField,
role: 'viewer',
} satisfies HubCollaborationCreateRequestV2025R0);
- lang: python
label: Create Box Hub collaboration
source: |-
client.hub_collaborations.create_hub_collaboration_v2025_r0(
CreateHubCollaborationV2025R0Hub(id=hub.id),
CreateHubCollaborationV2025R0AccessibleBy(type="user", id=user.id),
"viewer",
)
components:
parameters:
BoxVersionHeader:
name: box-version
in: header
description: Version header.
allowEmptyValue: false
required: true
schema:
type: string
enum:
- '2025.0'
example: '2025.0'
schemas:
HubCollaborationCreateRequest:
description: Request body for creating a new Box Hub collaboration.
type: object
properties:
hub:
description: Box Hubs reference.
type: object
properties:
type:
description: The value will always be `hubs`.
type: string
example: hubs
enum:
- hubs
id:
description: ID of the object.
type: string
example: '42037322'
required:
- type
- id
title: Box Hubs reference
accessible_by:
description: The user or group who gets access to the item.
type: object
properties:
type:
description: >-
The type of collaborator to invite. Possible values are `user`
or `group`.
type: string
example: user
id:
description: |-
The ID of the user or group.
Alternatively, use `login` to specify a user by email address.
type: string
example: '23522323'
login:
description: |-
The email address of the user who gets access to the item.
Alternatively, use `id` to specify a user by user ID.
type: string
example: john@example.com
required:
- type
role:
description: >-
The level of access granted to a Box Hub. Possible values are
`editor`, `viewer`, and `co-owner`.
type: string
example: editor
required:
- hub
- accessible_by
- role
title: Box Hub Collaboration Create Request
HubCollaboration:
description: >-
A Box Hub collaboration object grants a user or group access to a Box
Hub with permissions defined by a specific role.
type: object
properties:
id:
description: The unique identifier for this collaboration.
type: string
example: '12345678'
type:
description: The value will always be `hub_collaboration`.
type: string
example: hub_collaboration
enum:
- hub_collaboration
hub:
$ref: '#/components/schemas/Hub--Base'
accessible_by:
$ref: '#/components/schemas/HubAccessGrantee'
role:
description: >-
The level of access granted to a Box Hub. Possible values are
`editor`, `viewer`, and `co-owner`.
type: string
example: editor
status:
description: >-
The status of the collaboration invitation. If the status is
`pending`, `login` and `name` return an empty string.
type: string
example: accepted
enum:
- accepted
- pending
- rejected
acceptance_requirements_status:
type: object
properties:
terms_of_service_requirement:
type: object
properties:
is_accepted:
description: >-
Whether or not the terms of service have been accepted. The
field is `null` when there is no terms of service required.
type: boolean
example: true
nullable: true
terms_of_service:
allOf:
- $ref: '#/components/schemas/TermsOfService--Base'
- description: >-
The terms of service that must be accepted before the
collaboration can be accepted. The field is `null` when
there is no terms of service required.
strong_password_requirement:
type: object
properties:
enterprise_has_strong_password_required_for_external_users:
description: >-
Whether or not the enterprise that owns the content requires
a strong password to collaborate on the content, or enforces
an exposed password detection for the external
collaborators.
type: boolean
example: true
user_has_strong_password:
description: >-
Whether or not the user has a strong and not exposed
password set for their account. The field is `null` when a
strong password is not required.
type: boolean
example: true
nullable: true
two_factor_authentication_requirement:
type: object
properties:
enterprise_has_two_factor_auth_enabled:
description: >-
Whether or not the enterprise that owns the content requires
two-factor authentication to be enabled in order to
collaborate on the content.
type: boolean
example: true
user_has_two_factor_authentication_enabled:
description: >-
Whether or not the user has two-factor authentication
enabled. The field is `null` when two-factor authentication
is not required.
type: boolean
example: true
nullable: true
required:
- id
- type
title: Box Hub Collaboration
x-box-resource-id: hub_collaboration_v2025.0
x-box-tag: hub_collaborations
ClientError:
description: A generic error.
type: object
properties:
type:
description: The value will always be `error`.
type: string
example: error
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
type: integer
format: int32
example: 400
nullable: false
code:
description: A Box-specific error code.
type: string
example: item_name_invalid
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.
type: string
example: Method Not Allowed
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
example:
message: Something went wrong
additionalProperties: {}
nullable: true
help_url:
description: A URL that links to more information about why this error occurred.
type: string
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
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
title: Client error
x-box-resource-id: client_error_v2025.0
Hub--Base:
description: The bare basic representation of a Box Hub.
type: object
properties:
id:
description: >-
The unique identifier that represent a Box Hub.
The ID for any Box Hub can be determined by visiting a Box Hub in
the web application and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`.
type: string
example: '12345'
type:
description: The value will always be `hubs`.
type: string
example: hubs
enum:
- hubs
required:
- id
- type
title: Box Hub (Base)
x-box-resource-id: hub_v2025.0--base
x-box-tag: hubs
x-box-variant: base
x-box-variants:
- base
- standard
HubAccessGrantee:
description: The user or group that is granted access.
type: object
oneOf:
- $ref: '#/components/schemas/HubCollaborationUser'
- $ref: '#/components/schemas/Group--Mini'
title: Box Hub Accessible By
TermsOfService--Base:
description: >-
The root-level record that is supposed to represent a single Terms of
Service.
type: object
properties:
id:
description: The unique identifier for this terms of service.
type: string
example: '11446498'
type:
description: The value will always be `terms_of_service`.
type: string
example: terms_of_service
enum:
- terms_of_service
required:
- id
- type
title: Terms of service (Base)
HubCollaborationUser:
description: >-
A mini representation of a user, can be returned only when the status is
`pending`.
type: object
allOf:
- $ref: '#/components/schemas/User--Base'
- properties:
name:
description: >-
The display name of this user. If the collaboration status is
`pending`, an empty string is returned.
type: string
example: Aaron Levie
maxLength: 50
nullable: false
login:
description: >-
The primary email address of this user. If the collaboration
status is `pending`, an empty string is returned.
type: string
format: email
example: ceo@example.com
nullable: false
title: Box Hub Collaboration User
Group--Mini:
description: Mini representation of a group, including id and name of group.
type: object
allOf:
- $ref: '#/components/schemas/Group--Base'
- properties:
name:
description: The name of the group.
type: string
example: Support
group_type:
description: The type of the group.
type: string
example: managed_group
enum:
- managed_group
- all_users_group
title: Group (Mini)
User--Base:
description: >-
A mini representation of a user, used when nested within another
resource.
type: object
properties:
id:
description: The unique identifier for this user.
type: string
example: '11446498'
type:
description: The value will always be `user`.
type: string
example: user
enum:
- user
nullable: false
required:
- type
- id
title: User (Base)
Group--Base:
description: A base representation of a group.
type: object
properties:
id:
description: The unique identifier for this object.
type: string
example: '11446498'
type:
description: The value will always be `group`.
type: string
example: group
enum:
- group
required:
- id
- type
title: Group (Base)
securitySchemes:
OAuth2Security:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://account.box.com/api/oauth2/authorize
tokenUrl: https://api.box.com/oauth2/token
scopes:
root_readonly: Read all files and folders stored in Box
root_readwrite: Read and write all files and folders stored in Box
manage_app_users: Provision and manage app users
manage_managed_users: Provision and manage managed users
manage_groups: Manage an enterprise's groups
manage_webhook: Create webhooks programmatically through the API
manage_enterprise_properties: Manage enterprise properties
manage_data_retention: Manage data retention polices
manage_legal_hold: Manage Legal Holds
````