spaces/{space-id}

Method summary

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:

Response

Note: The following examples for Add, Update, and Delete operations are applicable for all spaces. If a subspace inherits permissions from a parent space, you must first disable space permissions inheritance before you call any of the operations.

Example 1 input - Add

• Add a user to a space:

  First, get the user ID with the UserList API, then use the following command.

  curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=add --header 'authorization:
  Bearer access_token' --header 'content-type: application/json'
  --data '{"users": [{"participantId": "5f500e1280001", "permissions": {"blueprintProcesses": false, "automateProcesses":
  true, "composeDecisions": false, "authorPolicies": true, "manageAndEdit": false}}]}'

• Add a default user-group (all-editors, all-contributors, all-community, all-viewers, all-admins) to a space:

  curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=add --header 'authorization:
  Bearer access_token' --header 'content-type: application/json'
  --data '{"users": [{"participantType": "all-contributors", "permissions": {"automateProcesses": true, "manageAndEdit":
  false}}]}'

• Add a custom user group to a space:

  First, get the user ID with the ManageGroup API, then use the following command.

  curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=add --header 'authorization:
  Bearer access_token' --header 'content-type: application/json'
  --data '{"users" : [{"participantId": "5f500e1280001", "permissions": {"blueprintProcesses": true,
  "automateProcesses": true, "composeDecisions": false, "authorPolicies": true, "manageAndEdit": false}}]}'

Example 2 input - Update

• Update user permissions:
  • User:

    curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=update --header
    'authorization: Bearer access_token' --header 'content-type:
    application/json' --data '{"users" : [{"participantId": "5f500e1280001", "permissions": {"blueprintProcesses": true,
    "automateProcesses": true, "composeDecisions": false, "authorPolicies": true, "manageAndEdit": false}}]}'

  • Default user group:

    curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=update --header
    'authorization: Bearer access_token' --header 'content-type:
    application/json' --data '{"users" : ["participantType": "all-editors", "permissions": {"blueprintProcesses": true,
    "automateProcesses": true, "composeDecisions": false, "authorPolicies": true, "manageAndEdit": false}}]}'

  • Custom user group:

    curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=update --header
    'authorization: Bearer access_token' --header 'content-type:
    application/json' --data '{"users" : [{"participantId": "5f500e1280001", "permissions": {"blueprintProcesses": true,
    "automateProcesses": true, "composeDecisions": false, "authorPolicies": true, "manageAndEdit": false}}]}'

• Disable "Inherit space permissions from a parent" for a subspace:

  curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=update --header
  'authorization: Bearer access_token' --header 'content-type:
  application/json' --data '{"inheritParentSpace": false}'

  Note: Use this command first if you want to call a Add, Update, or Delete operation in a subspace that inherits permissions from a parent space.

Example 3 input - Delete

• Delete a user from a space:

  curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=delete --header
  'authorization: Bearer access_token' --header 'content-type: 
  application/json' --data '{"users": [{"participantId": "5f500e1280001"}]}'

• Delete a default user group (all-editors, all-contributors, all-community, all-viewers, all-admins) from a space:

  curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=delete --header 
  'authorization: Bearer access_token' --header 'content-type: 
  application/json' --data '{"users": [{"participantType": "all-contributors"}]}'

• Delete a custom user group from a space:

  curl -i --request PUT --url https://your_server_url/bwl/spaces/{space-id}?operation=delete --header 
  'authorization: Bearer access_token' --header 'content-type: 
  application/json' --data '{"users" : [{"participantId": "5f500e1280001"}]}'

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 information, see OpenAPI specification.