Manage user access for restricted hubs

Shares or revokes access to a restricted hub for individual users in a single request.

Prerequisites

Authentication and setup: A valid access token.
Create a hub: The hub must exist and its access type must be HUB_ACCESS_RESTRICTED.

Endpoint

POST /api/assethub/v2/hub/{hub_id}/users/manage

Base URL: the standard REST host for your region. See 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

{
  "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

{
  "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.