Skip to main content
Box Hub collaborations control who can access a hub and at what role. You can invite users or groups by user ID, group ID, or email (for users). Roles are editor, viewer, and co-owner. You can only invite users who have a Box account (any plan) to collaborate on a hub.
Box Hubs endpoints require the box-version: 2025.0 header. If you omit this header, the API returns a 400 error with the message Missing required box-version header. Supported API versions: [2025.0]. For more information, see Box API versioning strategy.

​
Create a hub collaboration

To add a user or group to a hub, call the endpoint and provide:
  • The hub reference (HUB_ID)
  • The collaborator’s ID and type in the accessible_by field
  • The level of access granted to a hub in the role field

​
Create by user ID

curl -i -X POST "https://api.box.com/2.0/hub_collaborations" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0" \
     -H "Content-Type: application/json" \
     -d '{
       "hub": {
         "type": "hubs",
         "id": "HUB_ID"
       },
       "accessible_by": {
         "type": "user",
         "id": "USER_ID"
       },
       "role": "viewer"
     }'

​
Create by user email (login)

curl -i -X POST "https://api.box.com/2.0/hub_collaborations" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0" \
     -H "Content-Type: application/json" \
     -d '{
       "hub": {
         "type": "hubs",
         "id": "HUB_ID"
       },
       "accessible_by": {
         "type": "user",
         "login": "john@example.com"
       },
       "role": "editor"
     }'
Replace HUB_ID, USER_ID, and the email with real values. Valid role values are editor, viewer, and co-owner. A successful response returns the new object.

​
List hub collaborations

To list all collaborations for a hub, call the endpoint with the hub ID. 
curl -i -X GET "https://api.box.com/2.0/hub_collaborations?hub_id=HUB_ID" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0"
Optional query parameters: marker and limit. For details, see Marker-based pagination.

​
Get a hub collaboration by ID

To retrieve a single hub collaboration, call the endpoint with the collaboration ID. 
curl -i -X GET "https://api.box.com/2.0/hub_collaborations/HUB_COLLABORATION_ID" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0"

​
Update a hub collaboration

To change a collaborator’s role, call the endpoint with the hub collaboration ID and the new role. 
curl -i -X PUT "https://api.box.com/2.0/hub_collaborations/HUB_COLLABORATION_ID" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0" \
     -H "Content-Type: application/json" \
     -d '{
       "role": "editor"
     }'

​
Delete a hub collaboration

To remove a collaborator from a hub, call the endpoint with the hub collaboration ID. 
curl -i -X DELETE "https://api.box.com/2.0/hub_collaborations/HUB_COLLABORATION_ID" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "box-version: 2025.0"
A successful delete returns no body (HTTP 204).

​
Use cases

  • Onboarding automation: When a new hire is added to your HRIS, create a “Welcome Hub” and add them as a collaborator with the appropriate role.
  • Group-based access: Use the to find the right group, then add the group as a collaborator so all members get access.