provision/user

Use this resource to complete simple queries and user provisioning and deprovisioning requests. The user must be an account administrator.

Method summary

HTTP Method	Path	Description
GET	/scr/api/provision/user/	Retrieves details about a specific user account and lists all users in the account as a JSON array.
PUT	/scr/api/provision/user/	Adds a user or updates the user's membership in groups.
DELETE	/scr/api/provision/user/	Archives each user individually, removes a user from all groups, or removes a user from one or more specified groups.

GET /scr/api/provision/user/

Description

Use this method to retrieve details about a specific user account and list all account users in a JSON array.

The user provisioning service provides the following forms of a query method:

The base URI behaves as a collection URI and retrieves a list of users in the account as a JSON array.
The base URI with the user's email address behaves as an element URI and retrieves specific details about the account that is specified by the email address.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be an account administrator.
Supports OAuth 2 client credentials	Yes using a User Service ID containing User Management Category
Rate limited	Not yet

Parameters

Name	Location	Description	Required	Type
version	Header	The requested API version is `1.0`.	Yes	String

Response

Example input

LIST all users in the account: /scr/api/provision/user/

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" 
    -H "Version:1.0" "https://your_server_url/scr/api/provision/user"

GET the details of a specific user: /scr/api/provision/user/email_address

Important: The email_address parameter must be properly encoded.

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" 
    -H "Version:1.0" "https://your_server_url/scr/api/provision/user/user_id%40us.ibm.com"

Example output

LIST all users in the account:

HTTP/1.1 200 OK
{
  "users":["admin@us.ibm.com",
  "user_id@us.ibm.com","test@us.ibm.com"]
}

GET the details of a specific user:

HTTP/1.1 200 OK 
Content-Length: 108 
{
  "fullname": "John Smith",
  "username": "john.smith4@acme.com",
  "license": "VIEWER",
  "businessunit": { 
      "name": "Shipping",
      "id": "150007"
  },
  "admin": false,
  "active": true,
}

Response properties

username: The email address of the provisioned user.
fullname: The full name of the provisioned user. The default value is an empty string.
license: The license level of the provisioned user. The default value is EDITOR
admin: The value is true if the user is an administrator. Otherwise, the value is false.
active: The value is true if the user is active. Otherwise, the value is false.
businessunit: The department, division, workgroup, or functional area that the user works in.
usergroups: The list of groups that the user is a part of. This property is returned only if the user is a part of at least one group.
usergroups.groupname: The name of a group that the user is a part of.

Response messages

HTTP code	Reason
200 with JSON payload	The request was completed successfully.
400 with JSON payload	There was an error processing the request. Required parameters were missing or contained invalid values.
401	The user isn't authorized to make the request.
403	Access is forbidden. This message might appear for one of the following reasons: The specified credentials are invalid. This user isn't an editor for this process. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
404	The specified GET user is not found.

PUT /scr/api/provision/user/

Description

Use this method to add a user and update the user's membership in groups.

The base URI behaves as an add method. With the add method, when a previously archived user is added, the account of that user is reactivated.
The base URI with the username behaves as an update method. The update method is used to update the user's membership in one or multiple groups. If the username is non-existent, then a user is created with default attributes, as listed below.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be an account administrator.
Supports OAuth 2 client credentials	Yes using a User Service ID containing User Management Category
Rate limited	Not yet

Parameters

Name	Location	Description	Required	Type
content-type	Header	The value must be `application/json`.	Yes	String
version	Header	The requested API version is `1.0`.	Yes	String
JSON Request admin	JSON body	The parameter value, `true` or `false`, indicates whether the provisioned user must be an administrator. The default setting is `false`.	Yes	Boolean
JSON Request fullname	JSON body	The full name of the user to be provisioned. A blank full name is used if none is provided.	Yes	String
JSON Request license	JSON body	The license level of the user. The possible values are `VIEWER`, `COMMUNITY`, `CONTRIBUTOR`, or `EDITOR`. The license is set to default `EDITOR` level if none is provided.	Yes	String
JSON Request username	JSON body	The email address of the user to be provisioned.	Yes, when adding a new user.	String
JSON Request usergroups	JSON body	The JSON array of group names. Add user to the list of `usergroups`. The user is not added to the groups if the list is empty.	Yes, for updating.	JSON array of strings
businessunitid	JSON body	The ID of an existing business unit. The business unit must already exist.	No	String
businessunitname	JSON body	The name of a business unit. If a business unit with this name already exists, it is used. Otherwise, a new business unit is created. You can specify either the businessunitid or the businessunitname. If you provide both, the businessunitid takes precedence.	No	String

Response

Example input

Provision a specific user: /scr/api/provision/user/

Provision a user with only the required username parameter in the JSON Body:

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" 
    -X PUT --data "{\"username\":\"user1@us.ibm.com\"}" "https://your_server_url/scr/api/provision/user/"

Provision a user with all parameters in the JSON body:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" 
    -X PUT --data "{\"username\":\"john.smith@us.ibm.com\",\"fullname\":\"John Smith\",\"license\":\"EDITOR\",\"admin\":true,
    \"usergroups\":[{\"groupname\":\"group1\"},{\"groupname\":\"group2\"}]}" "https://your_server_url/scr/api/provision/user/"

Add an existing user to a group: /scr/api/provision/user/email_address

Important: The email_address parameter must be properly encoded.

Add a user to groups:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT 
    --data "{\"usergroups\":[{\"groupname\":\"group1\"},{\"groupname\":\"group2\"}]}" "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"

Add a user to an invalid group:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT 
    --data "{\"usergroups\":[{\"groupname\":\"invalid\"}]}" "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"

Add a new user and associate the user with an existing business unit using a business unit ID:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT
    --data "{\"username\":\"john.smith4@acme.com\",\"fullname\":\"John Smith\",\"license\":\"VIEWER\",\"admin\":false, \"businessunitid\":\"150007\"}" 
    "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"

Add a new user and associate the user with a business unit using a business unit name:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT 
    --data "{\"username\":\"john.smith4@acme.com\",\"fullname\":\"John Smith\",\"license\":\"VIEWER\",\"admin\":false, \"businessunitname\":\"Shipping\"}"
    "https://your_server_url/scr/api/provision/user/user1%40us.ibm.com"

Adding multiple users

A sample MS-DOS script is used to exercise the PUT request multiple times with values from a CSV file. The script maps the token to each column in the CSV file. More robust scripting with Perl, Python, or another language can also be used.

            for /f "tokens=1,2,3,4,5,6* delims=," %%a in (usersdetail.csv) do curl -i -H "Authorization: Bearer access_token" 
            -H "Version:1.0" -H "Content-Type:application/json" -X PUT --data 
            "{\"username\":\"%%a\", \"fullname\":\"%%b\",\"license\":\"%%c\",\"admin\":%%d,\"usergroups\":[{\"groupname\":\"%%e\"},{\"groupname\":\"%%f\"}]}" 
            "http://localhost:8080/scr/api/provision/user/"

The usersdetail.csv is then in the same directory as the batch script with the following sample content:

           abc@ibm.com,john smith,editor,true, groupA, groupB
           bac@ibm.com,smith john,community,false,group1, groupB

Note: The token is manually mapped to columns in the CSV file; therefore, it is best if all provisioned users belong to the same number of groups.

Example output

Provision a user with only the required username parameter in the JSON Body:

HTTP/1.1 200 OK 
Content-Length: 107
{"username":"user1@us.ibm.com","fullname":"","license":"EDITOR","admin":false,"active":true}

Provision a user with all parameters in the JSON body:

HTTP/1.1 200 OK 
Content-Length: 155
{"username":"john.smith@us.ibm.com","fullname":"John Smith","license":"EDITOR","admin":true,"active":true, 
"usergroups":[{"groupname":"group1"},{"groupname":"group2"}]}

Add a duplicate user:

HTTP/1.1 400 Bad Request  
Content-Length: 71
{"message":"The provided username is already a member of this account"}

Add a user to groups:

HTTP/1.1 200 
OK Content-Length: 107
{"username":"user1@us.ibm.com","fullname":"User One","license":"EDITOR","admin":true,"active":true, "usergroups":[{"groupname":"group1"},{"groupname":"group2"}]}

Add a user to an invalid group:

HTTP/1.1 400 Bad Request 
Content-Length: 79
{"message":"One of the provided groupname is either archived or is not valid."}

Response properties

username: The email address of the provisioned user.
fullname: The full name of the provisioned user. The default value is an empty string.
license: The license level of the provisioned user. The default value is EDITOR.
admin: The value is true if the user is an administrator. Otherwise, the value is false.
active: The value is true if the user is active. Otherwise, the value is false.
usergroups: The list of groups that the user is a part of. This is returned only if the user is a part of at least one group.
usergroups.groupname: The name of the group that the user is a part of.

Response messages

HTTP code	Reason
200 with JSON payload	The request was completed successfully.
400	There was an error processing the request. Check the JSON message element for details. This message might appear for one of the following reasons: The specified user already exists. There is an issue with the format or the licensing. .
401	The user isn't authorized to make the request.
403	Access is forbidden. This message might appear for one of the following reasons: The specified credentials are invalid. This user isn't an editor for this process. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
404	The specified user is not found.

DELETE /scr/api/provision/user/

Description: Use this method to archive each user individually, to remove a user from all groups, or to remove a user from one or more specified groups. The user archiving service provides a single form of the DELETE method, so there is no support for collections. This method can be called repeatedly to delete multiple users.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be an account administrator.
Supports OAuth 2 client credentials	Yes using a User Service ID containing User Management Category
Rate limited	Not yet

Parameters

Name	Location	Description	Required	Type
version	Header	The requested API version is `1.0`.	Yes	String
groups/group-id	Path	The identifier of the group to remove the user from. Use commas to separate multiple groups. To remove the user from all groups, use /groups.	No	String

Response

Example input

Important: The email_address parameter must be properly encoded.

Delete a specific user in the account: /scr/api/provision/user/email_address

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0"
     -X DELETE "https://your_server_url/scr/api/provision/user/user1%40domain.com"

Remove a user from all groups: /scr/api/provision/user/email_address/groups

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0"
    -X DELETE "https://your_server_url/scr/api/provision/user/user1%40domain.com/groups"

Remove a user from specified groups based on the group IDs. If there is more than one group, separate the group IDs with commas. /scr/api/provision/user/email_address/groups/group_ID

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0"
    -X DELETE "https://your_server_url/scr/api/provision/user/user1%40domain.com/groups/1310f8,180001"

Example output

Delete a user:

HTTP/1.1 200 OK  
Content-Length: 21
{"message":"Success"}

Delete a non-existent user:

HTTP/1.1 404 Not Found
Content-Length: 0

Remove a user from specified groups:

HTTP/1.1 200 OK  
Content-Length: 21
{"message":"Success"}

Response properties: None

Response messages

HTTP code	Reason
200 with JSON payload	The request was completed successfully.
400	There was an error processing the request. Check the JSON message element for details. This message might appear for one of the following reasons: The group ID is not valid or the group cannot be found. The user does not belong to the group. The user has Manage and Edit permissions for the group and cannot be removed.
401	The user isn't authorized to make the request.
403	Access is forbidden. This message might appear for one of the following reasons: The specified credentials are invalid. This user isn't an editor for this process. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
404	The requested user is not found.