---
title: "Manage user access for restricted hubs"
description: "Shares or revokes access to a restricted hub for individual users in a single request."
contentType: "api-reference"
url: "https://developer.mindtickle.com/docs/asset-hub/hubs/manage-user-access-for-restricted-hubs/"
---

## 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 and its access type must be HUB_ACCESS_RESTRICTED.

## Endpoint

```http
POST /api/assethub/v2/hub/{hub_id}/users/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 | ID of the hub for which you want to manage user access. |

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Required | Authorizer user ID. Must be a valid hex string. |
| `user_details` | array | Required | List of user entries to add or remove. Maximum 50 entries per request. |
| `user_details[].user_id` | string | Conditional | User ID. Primary identifier. Required if `username` is omitted. Takes precedence if both are provided. |
| `user_details[].username` | string | Conditional | Username. Required if `user_id` is omitted. |
| `user_details[].action` | string | Required | Operation to perform. `ADD` shares access to the hub, `REMOVE` revokes access to the hub. |

### Request example

```json
{
  "user_id": "123456789abcd101",
  "user_details": [
    {
      "user_id": "123456789abcd102",
      "username": "jane.doe",
      "action": "ADD"
    },
    {
      "username": "john.doe",
      "action": "REMOVE"
    }
  ]
}
```

## Response

| Field | Type | Description |
| --- | --- | --- |
| `request_id` | string | Unique ID for the request. |
| `hub_id` | string | The hub ID. |
| `status` | string | Overall status of the operation. `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILED`. |
| `success` | array | List of successfully processed entries. |
| `failed` | array | List of failed entries, each with an error `reason`. |

### Response example

```json
{
  "request_id": "req_101",
  "status": "PARTIAL_SUCCESS",
  "hub_id": "123456789012345103",
  "success": [
    {
      "user_id": "123456789abcd102",
      "username": "jane.doe",
      "action": "ADD"
    }
  ],
  "failed": [
    {
      "username": "john.doe",
      "action": "REMOVE",
      "reason": "User does not have access to this hub (hubId: 123456789012345103)"
    }
  ]
}
```

## Notes

- **Behavior:** This endpoint does the same as the "Share access" feature for individual users in the Asset Hub interface.
- **Status values:** `SUCCESS` means all entries succeeded, `PARTIAL_SUCCESS` means at least one entry succeeded and one failed, and `FAILED` means all entries failed.
- **Limits:** Maximum 50 entries per request.
- **Partial success:** Entries that pass validation are processed, and invalid entries are returned in the `failed` array. If all entries fail, the response is HTTP 200 with `status: FAILED`.
- **Validation:** The authorizer `user_id` must be a valid hex string.
- **Validation:** Each user entry must provide either `user_id` or `username`. If both are provided, `user_id` takes precedence and both values must resolve to the same user, otherwise a matching error is returned.
- **Limitations:** This endpoint applies to restricted hubs, where `access_type` is `HUB_ACCESS_RESTRICTED`, and not to public hubs.
- **Limitations:** This endpoint currently supports sharing or revoking access for individual users only, and not user groups, which are available in the Asset Hub interface.
- **Common error reasons:** `User not found with userId`, `No user found with username`, `User already has access to this hub` when adding existing access, `User does not have access to this hub` when removing missing access, and `Duplicate user in request`.

## Related

- [Manage hub collaborators](/docs/asset-hub/hubs/manage-hub-collaborators/): Grant or revoke hub-level permissions for collaborators.
- [List active hubs](/docs/asset-hub/hubs/list-active-hubs/): Find the hub ID to manage.