User and Group Management API

👤 This documentation is intended for Site Administrators.

<UL>
<LI><a href="#APIAuth">AUTHENTICATION</a></LI>
<LI>The User Management API allows clients to fetch, create, update and delete users with their group associations in a per site basis through a RESTful API. The User Management API includes:</LI>
<UL>
<LI><a href="#GetUsers">GET Users</a></LI>
<LI><a href="#GetSingleUser">GET Single User</a></LI>
<LI><a href="#CreateUser">CREATE User</a></LI>
<LI><a href="#UpdateUser">UPDATE User</a></LI>
<LI><a href="#DeleteUser">DELETE User</a></LI>
</UL>
<LI>The Group Management API similarly allows clients to fetch, create, update and delete groups. The Groups Management API includes:</LI>
<UL>
<LI><a href="#GetGroups">GET Groups</a></LI>
<LI><a href="#GetSingleGroup">GET Single Group</a></LI>
<LI><a href="#CreateGroup">CREATE Group</a></LI>
<LI><a href="#UpdateGroup">UPDATE Group</a></LI><
LI><a href="#DeleteGroup">DELETE Group</a></LI>
</UL>
<LI><a href="#LookingForMore">Looking For More?</a></LI>
</UL>

‍Note: User and Group Management API is available on select plans. Site administrators can contact their Customer Success Manager for additional information.

<HR>

Authentication

Find the site's hostname and API key. The site's hostname can be found in any dashboard URL. The API key can be found in the Billing and Authentication tab of the gear menu in the lower left-hand corner.

The API Key is unique to each site. Avoid exposing this API Key by storing them as environment variables. If an API Key has been accidentally revealed, please reach out to supportdt@sisense.com or the in-app live chat to get the API Key rotated.

To successfully authenticate against the API:

Base URL: https://app.periscopedata.com

Authentication: Http-X-Partner-Auth: <Site-Host:API-KEY>

Example:

<div>
<UL style="list-style-type:none;">
<li>For a site with:</li>
<UL style="list-style-type:none;">
<LI>dashboard URLs that look like '<b>https://app.periscopedata.com/app/example_site</b>'</LI>
<LI>sample API key of '<b>e179017a-62b0-4996-8a38-e91aa9f1</b>'.</LI>
<LI>The <b><Site-Host:API-KEY></b> would be <b><example_site:e179017a-62b0-4996-8a38-e91aa9f1></b></LI></UL>

The User Management API needs to be enabled on a given site for the endpoints to work. Otherwise, it will provide a 404 response.

<hr>

User Management API

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/v1/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>
"first_name": "Monica",<br>
"last_name": "Geller",<br>
"email": "monica@example.com",<br>
"groups": [<br>
"All Users"<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>
}<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 email_address in next_page_start and the clients make a call to ?next_page_start= to fetch the next 100 records and so on

GET Single User

<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/v1/users</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>
<br>
403 Forbidden if Http-X-Partner-Auth header not specified or API_KEY is incorrect or Site-Host does NOT exist<br>
<br>
400 if the email_address 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>
"first_name": "Chandler",<br>
"last_name": "Bing",<br>
"email": "chandler@example.com",<br>
"groups": [<br>
"All Users"<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>
}
</small></code>
</td>
</tr>
</tbody>
</table>
</div>

CREATE User

<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/v1/users</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 created
</td>
<td>POST</td>
<td>201 if user record is 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<br>
<br>
400 if the required fields are NOT specified or if they are invalid (first_name, last_name, email, invited_by_email)<br>
<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>groups</code></small></td>
<td><code><small><b>String[]</b></code></small></td>
<td><i>Optional</i></td>
<td>The groups that the new user will be a part of. This parameter is set to <code><small>["All Users"]</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>
</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>
"groups": [<br>
<b><i>string</i></b><br>
],<br>
"invited_by_email": <b><i>string</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>
"groups": [<br>
"All Users",<br>
"Sales"<br>
],<br>
"invited_by_email": "mike@example.com",<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>
"groups": [<br>
"All Users",<br>
"Sales"<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>
}
</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>

UPDATE User

<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/v1/users</td>
<td><b>REQUIRED HTTP HEADER:</b><br>
HTTP-X-EMAIL: <EMAIL_ADDRESS ><br>
<br>
<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>
400 if the the user does NOT exist for the site
</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>
"groups": [<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>
"groups": [<br>
"All Users",<br>
"NY Knicks"<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>
"first_name": "Joseph",<br>
"last_name": "Tribbiani",<br>
"email": "joey@example.com",<br>
"groups": [<br>
"All Users",<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>
}
</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 groups 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 groups to ["All Users"] <i>(default value for groups)</i><br>
<code><small>PUT { "first_name": "...", groups:[] } </small></code></td>
</tr>
<tr style="width:300px;text-align:left">
<td>#updates first_name and set groups to ["All Users"] <i>(default value for groups)</i><br>
<code><small>PUT {"first_name": "...", groups:["All Users"]}</small></code></td>
</tr>
</tbody>
</table>
</div>

DELETE User

Currently, when a user is deleted, the ownership over all the objects owned by deleted user is set to none.

<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/v1/users</td>
<td><b>REQUIRED HTTP HEADER:</b><br>
HTTP-X-EMAIL: <EMAIL_ADDRESS><br>
<br>
<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 deleted
</td>
<td>DELETE
</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>
400 if the the user does NOT exist for the site
</td>
</tr>
</tbody>
</table></div>

Example Response Body

<div>
<table>
<tbody>
<tr style="width:300px;text-align:left"><td><code><small>
{<br>
"message": "User removed from example-site"<br>
}
</small></code>
</td>
</tr>
</tbody>
</table>
</div>

<HR>

Group Management API

GET Groups

<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/v1/groups</td>
<td>next_page_start=<string> (Optional)</td>
<td>GET</td>
<td>200 if group 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_groups": 2,<br>
"groups_this_page": 2,<br>
"next_page_start": null,<br>
"groups": [<br>
{<br>
"name": "Administrators",<br>
"access": "Sql"<br>
}<br>
{<br>
"name": "All Users",<br>
"access": "Sql"<br>
}<br>
]<br>
}</small></code>
</td>
</tr>
</tbody>
</table>
</div>

GET Single Group

<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/v1/groups/{group_name}</td>
<td></td>
<td>GET</td>
<td>200 if group_name record is 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<br>
<br>
404 if the group_name does NOT exist 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>
"name": "Administrators",<br>
"access": "Sql",<br>
"dashboards": [<br>
{<br>
"name": "Example Dashboard",<br>
"access": "Edit"<br>
}<br>
{<br>
"name": "Test Dashboard",<br>
"access": "Edit"<br>
}<br>
]<br>
}</small></code>
</td>
</tr>
</tbody>
</table>
</div>

CREATE Group

<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/v1/groups/</td>
<td><b>OPTIONAL PARAMETER</b><br>
?test_mode=true <br>
<br>
If this parameter is set, then ONLY VALIDATIONS run and the actual group does NOT get created
</td>
<td>POST</td>
<td>201 if group record is 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<br>
<br>
400 if the required fields are NOT specified or if they are invalid (name and access)<br>
<br>
400 if the access is NOT one of sql/discovery/view<br>
<br>
409 if the group already exists
</td>
</tr>
</tbody>
</table></div>

Request Body

<div><table><tbody>
<tr><td><code><small>
{<br>
"name": <b><i>string</i></b>,<br>
"access": <b><i>string</i></b>,<br>
"created_by_email": <b><i>string</i></b>,<br>
}</code></small>
</td></tr></tbody></table></div>

Example Request Body

<div><table><tbody>
<tr><td><code><small>
{<br>
"name": "Friends",<br>
"access": "Sql",<br>
“created_by_email”: “rachel@example.com”<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>
"name": "Friends",<br>
"access": "Sql"<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>

Note: The backend logic will "view/sql/discovery" and perform the following mapping in the group_role table

Group_role table mapping:

<div><table><thead><tr>
<th style="width:250px;text-align:left"><b>Access</b></th>
<th style="width:300px;text-align:left"><b>can_edit column</b></th>
<th style="width:300px;text-align:left"><b>can_drag_and_drop column</b></th>
</tr></thead>
<tbody><tr>
<td>View</td>
<td>false</td>
<td>false</td></tr>
<tr>
<td>SQL</td>
<td>true</td>
<td>false</td>
</tr>
<tr>
<td>Discovery</td>
<td>false</td>
<td>true</td>
</tr></tbody></table></div>

UPDATE Group

<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/v1/groups/{group_name}</td>
<td><b>OPTIONAL PARAMETER:</b><br>
?test_mode=true <br>
<br>
If this parameter is set, then ONLY VALIDATIONS run and the actual group 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>
400 if the access is NOT one of sql/discovery/view
</td>
</tr>
</tbody>
</table></div>

Request Body

<div><table><tbody>
<tr><td><code><small>
{<br>
"name": <b><i>string</i></b>,<br>
"access": <b><i>string</i></b>,<br>
}</code></small>
</td></tr></tbody>
</table></div>

Example Request Body

<div><table><tbody>
<tr><td><code><small>
{<br>
"name": "Friends",<br>
"access": "Sql",<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>
"name": "Friends",<br>
"access": "Sql",<br>
}
</small></code>
</td>
</tr>
</tbody>
</table>
</div>

Some More Examples

<div>
<table>
<tbody>
<tr style="width:300px;text-align:left">
<td>#updates only group name.<br>
<code><small>PUT { "name": "..." }</small></code></td>
</tr>
<tr style="width:300px;text-align:left">
<td>#updates only group access<br>
<code><small>PUT { "access": "" }</small></code></td>
</tr>
<tr style="width:300px;text-align:left">
<td>#updates both group name and access<br>
<code><small>PUT { "name": "...", "access": "" }</small></code></td>
</tr>
</tbody>
</table>
</div>

DELETE Group

<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/v1/groups/{group_name}</td>
<td><b>OPTIONAL PARAMETER</b><br>
?test_mode=true<br>
<br>
If this parameter is set, then ONLY VALIDATIONS run and the actual group does NOT get deleted
</td>
<td>DELETE
</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 group 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>
"message": "Group removed from example-site"<br>
}
</small></code>
</td>
</tr>
</tbody>
</table>
</div>

‍

Looking for More?

Refer to our community for examples on implementing the above API calls

‍

User and Group Management API

Table of Contents:

Authentication

To successfully authenticate against the API:

User Management API

GET Users

Example Response Body

GET Single User

Example Response Body

CREATE User

Request Body

Example Request Body

Example Response Body

UPDATE User

Request Body

Example Request Body

Example Response Body

Some More Examples

DELETE User

Example Response Body

Group Management API

GET Groups

Example Response Body

GET Single Group

Example Response Body

CREATE Group

Request Body

Example Request Body

Example Response Body

UPDATE Group

Request Body

Example Request Body

Example Response Body

Some More Examples

DELETE Group

Example Response Body

Looking for More?