---
title: "Manage hub collaborators"
description: "Adds or removes hub-level permissions for multiple collaborators on a hub in a single request."
contentType: "api-reference"
url: "https://developer.mindtickle.com/docs/asset-hub/hubs/manage-hub-collaborators/"
---

## Prerequisites

1. [Authentication and setup](/docs/getting-started/authentication-and-setup/): A valid access token.
2. [Create a hub](/docs/asset-hub/hubs/create-a-hub/): The hub must exist.

## Endpoint

```http
POST /api/assethub/v1/hub/{hub_id}/collaborators/manage
```

Base URL: the standard REST host for your region. See [Base URLs](/docs/getting-started/authentication-and-setup/#base-urls).

Headers: `Authorization: Bearer ACCESS_TOKEN`, `Content-Type: application/json`.

## Path parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `hub_id` | string | The hub ID. Must match the hub for which collaborators are being managed. |

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Required | ID of the user performing the operation. Must have the `HUB_MANAGEMENT` permission on the hub. |
| `collaborator_details` | array | Required | List of collaborator entries to add or remove. Maximum 50 entries per request. |
| `collaborator_details[].collaborator_user_id` | string | Conditional | User ID of the collaborator. Either `collaborator_user_id` or `collaborator_username` is required. |
| `collaborator_details[].collaborator_username` | string | Conditional | Username, the email, of the collaborator. Either `collaborator_user_id` or `collaborator_username` is required. |
| `collaborator_details[].permissions` | string[] | Required | List of permissions to add or remove. One or more of `DEVELOP_ASSETS`, `HUB_MANAGEMENT`, `SHARE_HUB_ACCESS`, `VIEW_HUB_ANALYTICS`. |
| `collaborator_details[].action` | string | Required | Operation to perform. `ADD` or `REMOVE`. |

### Request example

```json
{
  "user_id": "123456789abcd101",
  "collaborator_details": [
    {
      "collaborator_username": "jane@example.com",
      "permissions": ["DEVELOP_ASSETS", "SHARE_HUB_ACCESS"],
      "action": "ADD"
    },
    {
      "collaborator_user_id": "123456789abcd102",
      "collaborator_username": "bob@example.com",
      "permissions": ["VIEW_HUB_ANALYTICS"],
      "action": "REMOVE"
    }
  ]
}
```

## Response

| Field | Type | Description |
| --- | --- | --- |
| `request_id` | string | Unique ID for the request. |
| `hub_id` | string | The hub ID. |
| `status` | string | Overall status: `SUCCESS` if all entries succeed, `PARTIAL_SUCCESS` if at least 1 succeeds and 1 fails, or `FAILED` if all fail or none are valid to process. |
| `collaborator_details` | array | List of successfully processed entries. Each entry contains `result`, either `ADDED` or `REMOVED`. |
| `failure_details` | array | List of failed entries, each with an error `reason`. |

### Response example

```json
{
  "request_id": "req_101",
  "hub_id": "123456789012345103",
  "status": "PARTIAL_SUCCESS",
  "collaborator_details": [
    {
      "collaborator_username": "jane@example.com",
      "action": "ADD",
      "result": "ADDED",
      "permissions": ["DEVELOP_ASSETS", "SHARE_HUB_ACCESS"]
    }
  ],
  "failure_details": [
    {
      "collaborator_user_id": "123456789abcd102",
      "collaborator_username": "bob@example.com",
      "action": "REMOVE",
      "reason": "Permission does not exist for user"
    }
  ]
}
```

## Notes

- **Actions:** `ADD` grants access to the specified users and adds them as collaborators on the hub. `REMOVE` revokes access and removes them from the hub's collaborator list.
- **Limits:** Maximum 50 collaborator entries per request.
- **Partial success:** Entries that pass validation are processed, and invalid entries are returned in the `failure_details` array. If all entries fail static validation, the response is HTTP 200 with `status: FAILED`.
- **Validation:** Each collaborator entry must specify either `collaborator_user_id` or `collaborator_username`. When both are provided, `collaborator_user_id` takes precedence and both values must resolve to the same user, otherwise a matching error is returned.
- **Validation:** The `permissions` array cannot be empty.
- **Limitations:** The Asset Hub interface supports both users and user groups, but this endpoint currently supports managing collaborator access for individual users only.
- **Common error reasons:** `User not found by User ID`, `User not found by Username / Email`, `Permission is at override level and cannot be removed`, `Permission does not exist for user` when removing a permission the user does not have, and `User already has this permission` when adding a permission the user already has.

## Related

- [Manage user access for restricted hubs](/docs/asset-hub/hubs/manage-user-access-for-restricted-hubs/): Share or revoke access for individual users on a restricted hub.
- [List active hubs](/docs/asset-hub/hubs/list-active-hubs/): Find the hub ID to manage.