User Management API for Self Service Dashboards
👤 This documentation is intended for Site Administrators.
Note: Self Service Dashboards is an additional feature. Site administrators can contact their Account Manager for additional information.
Note: Site Admins should refer to the User and Group Management API documentation for customers that do not have Role-Based Access Control (RBAC) enabled.
Table of Contents:
<UL>
<LI><a href="#CreateUser">CREATE User</a></LI>
<LI><a href="#UpdateUser">UPDATE User</a></LI>
<LI><a href="#GetUsers">GET Users</a></LI>
<LI><a href="#GetSingleUser">GET Single User</a></LI>
<LI><a href="#LookingForMore">Looking For More?</a></LI>
</UL>
<HR>
<a name="CreateUser"></a>
Create User with Self Service Access
<div>
<table>
<thead>
<tr><th style="width:200px;text-align:left">URL</th>
<th style="width:200px;text-align:left">Parameters/HTTP Header</th>
<th style="width:300px;text-align:left">HTTP VERB</th>
<th style="width:300px;text-align:left">Response Codes</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/v2/users</td>
<td><b>OPTIONAL PARAMETER</b><br>
?test_mode=true <br>
If this parameter is set, then ONLY VALIDATIONS run and the actual user does NOT get created
</td>
<td>POST</td>
<td>201 if user record is successfully returned<br>
403 Forbidden if Http-X-Partner-Auth header not specified or API_KEY is incorrect or Site-Host does NOT exist<br>
400 if the required fields are NOT specified or if they are invalid (first_name, last_name, email, invited_by_email) or if the site is not configured for Dashboards<br>
409 if the email_address already exists
</td>
</tr>
</tbody>
</table></div>
<div><table>
<thead>
<tr>
<th style="width:175px;text-align:left">Argument</th>
<th style="width:100px;text-align:left">Type</th>
<th style="width:100px;text-align:left"></th>
<th style="width:600px;text-align:left">Description</th>
<tbody>
<tr>
<td><code><small>first_name</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>New user's first name.</td>
</tr>
<tr>
<td><code><small>last_name</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>New user's last name.</td>
</tr>
<tr>
<td><code><small>email</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>New user's email address.</td>
</tr>
<tr>
<td><code><small>roles</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>The role ids that the new user will be a part of. This parameter is set to <code><small>["Everyone"]</code></small> by default.</td>
</tr>
<tr>
<td><code><small>invited_by_email</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>Inviter's email address. The inviter must have access to create a user.</td>
</tr>
<tr>
<td><code><small>platforms</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>The platforms that the new user will be a part of “workbooks” and “dashboards”. The parameter <code><small>["workbooks"]</code></small> will be granted if platform is not specified.</td>
</tr>
</tbody>
</table></div>
Request Body
<div><table><tbody>
<tr><td><code><small>
{<br>
"first_name": <b><i>string</i></b>,<br>
"last_name": <b><i>string</i></b>,<br>
"email": <b><i>string</i></b>,<br>
"roles": [<br>
<b><i>string</i></b><br>
],<br>
"invited_by_email": <b><i>string</i></b>,<br>
"platforms": <b><i>[(string: “workbooks”, “dashboards”)]</i></b><br>
}</code></small>
</td></tr></tbody></table></div>
Example Request Body
<div><table><tbody>
<tr><td><code><small>
{<br>
"first_name": "Phoebe",<br>
"last_name": "Buffay",<br>
"email": "phoebe@example.com",<br>
"roles": [<br>
"7000-3v3ry-1",<br>
"00000-Custom-333-roleid"<br>
],<br>
"invited_by_email": "mike@example.com",<br>
"platforms": [( “workbooks”, “dashboards”)]<br>
}
</code></small>
</td></tr></tbody></table></div>
Example Response Body
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left"><td><code><small>
{<br>
"first_name": "Phoebe",<br>
"last_name": "Buffay",<br>
"email": "phoebe@example.com",<br>
"roles": [<br>
"7000-3v3ry-1",<br>
"00000-Custom-333-roleid"<br>
],<br>
"last_login_at": "2019-02-06T23:46:07.118Z",<br>
"password_updated_at": "2018-10-18T20:08:41.794Z",<br>
"tfa_enabled": true,<br>
"platforms": "workbooks"<br>
}
</small></code>
</td>
</tr>
<tr><td><br>
If test_mode=true is specified, the response body is<br>
<code><small>{<br>
"message": "Action would have completed successfully"<br>
}</small></code>
</td></tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="UpdateUser"></a>
Update User with Self Service Dashboards
<div>
<table>
<thead>
<tr>
<th style="width:200px;text-align:left">URL</th>
<th style="width:200px;text-align:left">Parameters</th>
<th style="width:300px;text-align:left">HTTP VERB</th>
<th style="width:300px;text-align:left">Response Codes</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/v2/users/<id></td>
<td><b>OPTIONAL PARAMETER:</b><br>?test_mode=true<br><br>If this parameter is set, then ONLY VALIDATIONS run and the actual user does NOT get updated </td>
<td>PUT</td>
<td>200 if operation is successful<br>
<br>403 Forbidden if Http-X-Partner-Auth header not specified or API_KEY is incorrect or Site-Host does NOT exist<br>
<br>404 if the the user id does NOT exist for the site
<br>400 if the site is not configured for Self Service Dashboards</td>
</tr>
</tbody>
</table>
</div>
<div>
<table>
<thead>
<tr>
<th style="width:175px;text-align:left">Argument</th>
<th style="width:100px;text-align:left">Type</th>
<th style="width:100px;text-align:left"></th>
<th style="width:600px;text-align:left">Description</th>
<tbody>
<tr>
<td><code><small>first_name</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>Update user's first name.</td>
</tr>
<tr>
<td><code><small>last_name</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>Update's last name.</td>
</tr>
<tr>
<td><code><small>roles</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>Updates roles that the user will be a part of. This parameter is set to <code><small>["Everyone"]</code></small> by default.</td>
</tr>
<tr>
<td><code><small>platforms</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>Updates platform that the user will be a part of. If this parameter is not specified then there will not be change to platform access.</td>
</tr>
</tbody>
</table>
</div>
Request Body
Any permutation of the following fields is acceptable.
<div>
<table>
<tbody>
<tr>
<td><code><small>{
<br> "first_name": <b><i>string</i></b>,
<br> "last_name": <b><i>string</i></b>,
<br> "roles": [
<br> <b><i>string</i></b><br> ],
<br> "platforms": [
<br> <b><i>string</i></b><br> ]
<br>}</code></small></td>
</tr>
</tbody>
</table>
</div>
Example Request Body
<div>
<table>
<tbody>
<tr>
<td><code><small>{
<br> "first_name": "Joseph",
<br> "last_name": "Tribbiani",
<br> "roles": [
<br> "7000-3v3ry-1",
<br> "00000-Custom-333-roleid"
<br> ],
<br> "platforms": [
<br> "workbooks",
<br> "dashboards"
<br> ]
<br>}</code></small></td>
</tr>
</tbody>
</table>
</div>
Example Response Body
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left">
<td><code><small>{
<br> "id": "1234-User-1d"
<br> "first_name": "Joseph",
<br> "last_name": "Tribbiani",
<br> "email": "joey@example.com",
<br> "roles": [
<br> {
<br> "7000-3v3ry-1",
<br> "Everyone"
<br> }
<br> {
<br> "00000-Custom-333-roleid",
<br> "NY Knicks"
<br> ],
<br> "last_login_at": "2014-02-06T23:46:07.118Z",
<br> "password_updated_at": "2018-10-18T20:08:41.794Z",
<br> "tfa_enabled": true,
<br> "platform": ["workbooks","dashboards"]
<br>}</small></code></td>
</tr>
</tbody>
</table>
</div>
Some More Examples
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left">
<td>#updates only first_name since no roles are passed in.<br><code><small>PUT { "first_name": "..." }</small></code></td>
</tr>
<tr style="width:300px;text-align:left">
<td>#updates first_name and set roles to ["Everyone"] <i>(default value for roles)</i><br><code><small>PUT { "first_name": "...", roles:[] } </small></code></td>
</tr>
<tr style="width:300px;text-align:left">
<td>#updates first_name and set roles to ["Everyone"] <i>(default value for roles)</i><br><code><small>PUT {"first_name": "...", roles:["7000-3v3ry-1"]}</small></code></td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="GetUser"></a>
GET Users
<div><table>
<thead>
<tr>
<th style="width:200px;text-align:left">URL</th>
<th style="width:200px;text-align:left">Parameters</th>
<th style="width:300px;text-align:left">HTTP VERB</th>
<th style="width:300px;text-align:left">Response Codes</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/v2/users</td>
<td>next_page_start=<string> (Optional)</td>
<td>GET</td>
<td>200 if user records are successfully returned<br>
<br>403 Forbidden if Http-X-Partner-Auth header not specified or API_KEY is incorrect or Site-Host does NOT exist
</td>
</tr>
</tbody>
</table></div>
Example Response Body
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left"><td><code><small>
{<br>
"total_users": 1,<br>
"users_this_page": 1,<br>
"next_page_start": null,<br>
"users": [<br>
{<br>
"id": "FR13ND5-85b5",<br>
"first_name": "Monica",<br>
"last_name": "Geller",<br>
"email": "monica@example.com",<br>
"roles": [<br>
{ <br>
"id":"7000-3v3ry-1",<br>
"role":"Everyone"<br>
}<br>
],<br>
"last_login_at": "2014-02-06T23:46:07.118Z",<br>
"password_updated_at": "2018-10-18T20:08:41.794Z",<br>
"tfa_enabled": true,<br>
"platforms": ["workbooks","dashboards"]<br>
}<br>
]<br>
}</small></code>
</td>
</tr>
</tbody>
</table>
</div>
The API only returns 100 records. If there are more than 100 users, the API returns an id in next_page_start and the clients make a call to ?next_page_start=<id> to fetch the next 100 records and so on
<a href="#top">Back to top</a>
<a name="GetSingleUser"></a>
Get Single User in Self Service Dashboards
<div><table>
<thead>
<tr>
<th style="width:200px;text-align:left">URL</th>
<th style="width:200px;text-align:left">HTTP Headers</th>
<th style="width:300px;text-align:left">HTTP VERB</th>
<th style="width:300px;text-align:left">Response Codes</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/v2/users/id<id></td>
<td><b>REQUIRED HTTP HEADER:</b><br>
HTTP-X-EMAIL: <EMAIL_ADDRESS ></td>
<td>GET</td>
<td>200 if user record is successfully returned<br>
403 Forbidden if Http-X-Partner-Auth header not specified or API_KEY is incorrect or Site-Host does NOT exist<br>
400 if the id does NOT belong to the user on this site
</td>
</tr>
</tbody>
</table>
</div>
Example Response Body
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left"><td><code><small>
{<br>
"id": "0000-examp-le999-0000id" <br>
"first_name": "Chandler",<br>
"last_name": "Bing",<br>
"email": "chandler@example.com",<br>
"roles": [<br>
{<br>
"id":"7000-3v3ry-1" ,<br>
"Everyone"<br>
},<br>
{<br>
"id":"00000-Custom-333-roleid"
"name":"Custom_role"<br>
}
],<br>
"last_login_at": "2019-02-06T23:46:07.118Z",<br>
"password_updated_at": "2018-10-18T20:08:41.794Z",<br>
"tfa_enabled": true,<br>
"platforms": ["workbooks","dashboards"]<br>
}
</small></code>
</td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
