spaces/{space-id}
Use this resource to modify the permissions of users or user-groups for a space.
Method summary
HTTP Method | Path | Description |
---|---|---|
PUT | /bwl/spaces/{spaces-id} | Modifies the permissions of users or user-groups for a space. |
PUT /spaces/{space-id}
- Description
- Use this method to add, edit, or delete the permissions of user or user-groups for a space.
- Resource information
-
Requirements Description Response format JSON Requires authentication Yes Supports OAuth 2 client credentials Yes using a User Service ID containing Artifact Authoring Category Rate limited IBM Blueworks Live applies a rate limit that determines how often this API can be called within a specific period. The allowed rate is 200 requests per hour. The rate limit is applied to the whole account. Even if different authentication methods are used, the single account-wide rate is applied across all users.
When the rate limit for the API is exceeded for the account, the next request is rejected with status code 429 and response header
Retry-After
, which indicates the number of seconds when the next request can be made.
- Parameters
-
Name Location Description Required Type space-id Path The identifier of the space. Yes String operation Query The type of operation. The operations include: Add, Update, Delete
.Yes String Content-type Header The value must be application/json Required when there is content in the request body String X-On-Behalf-Of Header The user context. The value must be a username in the account. The user must have permission to perform the action in the account and in the specified space, if any. Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential. String
- Request JSON body
-
The request body is a JSON object containing the following properties:
Name | Location | Description | Required | Type |
---|---|---|---|---|
inheritParentSpace | JSON body | Specifies whether the space inherits the permissions of its parent. | No | Boolean |
users | JSON array | JSON object containing a list of users. | Yes | String |
participantId | JSON body | The IDs of users or user groups. Tip: Use UserList API (version: 20110917) and
ManageGroup API (version: 2.0) to retrieve the values of participantId for the
request.
For more information, see:UserList and ManageGroup |
Yes, if participantType is not specified. Either participantId or participantType is mandatory. |
String |
participantType | JSON body | The possible values are: all-editors , all-contributors ,
all-community , all-viewers ,
all-admins . |
Yes, if participantId is not specified. Either participantId or participantType is mandatory. |
String |
permissions | JSON body | JSON object specifying the permissions of the user. The permissions include:
blueprintProcesses , automateProcesses ,
composeDecisions , authorPolicies , and
manageAndEdit . |
Yes Note: Only permissions suitable for the license type are required.
|
Object |
- Response
-
- Example 1 input - Add a user/user group:
-
- Add a User to User Permissions in a space with operation 'add' and JSON Body:
curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=add --header 'authorization: Bearer access_token' --header 'X-On-Behalf-Of: user_name@domain.com' --header 'content-type: application/json' --data '{"users": [{"participantId": "5f500e1280001", "permissions": {"blueprintProcesses": false, "automateProcesses": true, "composeDecisions": false, "authorPolicies": true, "manageAndEdit": false}}]}'
- Example 2 input - Update a user/user group:
-
- Update a Custom Group in User Permissions in a space with operation 'update' and JSON Body:
curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=update --header 'authorization: Bearer access_token' --header 'X-On-Behalf-Of: user_name@domain.com' --header 'content-type: application/json' --data '{"users" : [{"participantId": "5f500e1280001", "permissions": {"blueprintProcesses": true, "automateProcesses": true, "composeDecisions": false, "authorPolicies": true, "manageAndEdit": false}}]}'
- If
inheritParentSpace
is true, it must be updated to false in order to add/update/delete a user/user group.
curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=update --header 'authorization: Bearer access_token' --header 'X-On-Behalf-Of: user_name@domain.com' --header 'content-type: application/json' --data '{"inheritParentSpace": false}'
- Example 3 input - Delete a user/user group:
-
Delete a Default Group from User Permissions in a space with operation 'delete' and JSON Body:
curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=delete --header 'authorization: Bearer access_token' --header 'X-On-Behalf-Of: user_name@domain.com' --header 'content-type: application/json' --data '{"users": [{"participantType": "all-editors"}]}'
- Example output
-
If the request is successful, a
“200 OK” "Updated Space permissions"
message is returned. - Response headers
-
Header name Description Retry-After When the next request can be made, in a number of seconds - Response messages
-
HTTP code Reason 200 The request was completed successfully.
400 There is an error processing the request. Required parameters were missing or contained invalid values.
401 This user didn't pass authentication. This response could appear for the following reasons:- An invalid username or password was provided.
- This user belongs to multiple accounts and an account wasn't specified in the request.
403 This user does not have permission to modify the permissions of a space in this account
404 The space-ID does not exist.
429 The request exceeded the rate limit of the API for this account.
For more details, refer: Viewing OpenAPI specification file with Swagger editor.