Manage hub collaborations

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

box hubs:collaborations:create HUB_ID --role viewer --user-id 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"
     }'

await client.hubCollaborations.createHubCollaborationV2025R0({
  hub: new HubCollaborationCreateRequestV2025R0HubField({ id: hub.id }),
  accessibleBy: {
    type: 'user',
    id: user.id,
  } satisfies HubCollaborationCreateRequestV2025R0AccessibleByField,
  role: 'viewer',
} satisfies HubCollaborationCreateRequestV2025R0);

client.hub_collaborations.create_hub_collaboration_v2025_r0(
    CreateHubCollaborationV2025R0Hub(id=hub.id),
    CreateHubCollaborationV2025R0AccessibleBy(type="user", id=user.id),
    "viewer",
)

await client.HubCollaborations.CreateHubCollaborationV2025R0Async(requestBody: new HubCollaborationCreateRequestV2025R0(hub: new HubCollaborationCreateRequestV2025R0HubField(id: hub.Id), accessibleBy: new HubCollaborationCreateRequestV2025R0AccessibleByField(type: "user") { Id = user.Id }, role: "viewer"));

try await client.hubCollaborations.createHubCollaborationV2025R0(requestBody: HubCollaborationCreateRequestV2025R0(hub: HubCollaborationCreateRequestV2025R0HubField(id: hub.id), accessibleBy: HubCollaborationCreateRequestV2025R0AccessibleByField(type: "user", id: user.id), role: "viewer"))

client.getHubCollaborations().createHubCollaborationV2025R0(new HubCollaborationCreateRequestV2025R0(new HubCollaborationCreateRequestV2025R0HubField(hub.getId()), new HubCollaborationCreateRequestV2025R0AccessibleByField.Builder("user").id(user.getId()).build(), "viewer"));

box hubs:collaborations:create HUB_ID --role editor --login john@example.com

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"
     }'

client.hub_collaborations.create_hub_collaboration_v2025_r0(
    CreateHubCollaborationV2025R0Hub(id=hub.id),
    CreateHubCollaborationV2025R0AccessibleBy(type="user", login="john@example.com"),
    "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.

box hubs:collaborations 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"

await client.hubCollaborations.getHubCollaborationsV2025R0({
  hubId: hub.id,
} satisfies GetHubCollaborationsV2025R0QueryParams);

client.hub_collaborations.get_hub_collaborations_v2025_r0(hub.id)

await client.HubCollaborations.GetHubCollaborationsV2025R0Async(queryParams: new GetHubCollaborationsV2025R0QueryParams(hubId: hub.Id));

try await client.hubCollaborations.getHubCollaborationsV2025R0(queryParams: GetHubCollaborationsV2025R0QueryParams(hubId: hub.id))

client.getHubCollaborations().getHubCollaborationsV2025R0(new GetHubCollaborationsV2025R0QueryParams(hub.getId()));

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.

box hubs:collaborations:get HUB_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"

await client.hubCollaborations.getHubCollaborationByIdV2025R0(hubCollaborationId);

client.hub_collaborations.get_hub_collaboration_by_id_v2025_r0(hub_collaboration_id)

await client.HubCollaborations.GetHubCollaborationByIdV2025R0Async(hubCollaborationId: hubCollaborationId);

client.getHubCollaborations().getHubCollaborationByIdV2025R0(hubCollaborationId);

Update a hub collaboration

To change a collaborator’s role, call the endpoint with the hub collaboration ID and the new role.

box hubs:collaborations:update HUB_COLLABORATION_ID --role editor

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"
     }'

await client.hubCollaborations.updateHubCollaborationByIdV2025R0(hubCollaborationId, {
  role: 'editor',
} satisfies HubCollaborationUpdateRequestV2025R0);

client.hub_collaborations.update_hub_collaboration_by_id_v2025_r0(hub_collaboration_id, role="editor")

await client.HubCollaborations.UpdateHubCollaborationByIdV2025R0Async(hubCollaborationId: hubCollaborationId, requestBody: new HubCollaborationUpdateRequestV2025R0() { Role = "editor" });

client.getHubCollaborations().updateHubCollaborationByIdV2025R0(hubCollaborationId, new HubCollaborationUpdateRequestV2025R0.Builder().role("editor").build());

Delete a hub collaboration

To remove a collaborator from a hub, call the endpoint with the hub collaboration ID.

box hubs:collaborations:delete 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"

await client.hubCollaborations.deleteHubCollaborationByIdV2025R0(hubCollaborationId);

client.hub_collaborations.delete_hub_collaboration_by_id_v2025_r0(hub_collaboration_id)

await client.HubCollaborations.DeleteHubCollaborationByIdV2025R0Async(hubCollaborationId: hubCollaborationId);

client.getHubCollaborations().deleteHubCollaborationByIdV2025R0(hubCollaborationId);

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.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Manage hub collaborations

Create a hub collaboration

Create by user ID

List hub collaborations

Get a hub collaboration by ID

Update a hub collaboration

Delete a hub collaboration

Use cases

​Create a hub collaboration

​Create by user ID

​Create by user email (login)

​List hub collaborations

​Get a hub collaboration by ID

​Update a hub collaboration

​Delete a hub collaboration

​Use cases

Create a hub collaboration

Create by user ID

Create by user email (login)

List hub collaborations

Get a hub collaboration by ID

Update a hub collaboration

Delete a hub collaboration

Use cases