User and Role Management API - RBAC
👤 This documentation is intended for Site Administrators.
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="#APIAuth">AUTHENTICATION</a></LI>
<LI>The User Management API allows Admins to fetch, create, update and delete users with their role 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 Role Management API similarly allows Admins to fetch, create, update and delete roles. The Roles Management API includes:</LI>
<UL>
<LI><a href="#Getroles">GET Roles</a></LI>
<LI><a href="#GetSinglerole">GET Single Role</a></LI>
<LI><a href="#Createrole">CREATE Role</a></LI>
<LI><a href="#Updaterole">UPDATE Role</a></LI>
<LI><a href="#Deleterole">DELETE Role</a></LI>
</UL>
<LI>The Dashboard API similarly allows Admins to fetch dashboards to be able to set permissions on those dashboards. The Dashboard API includes:</LI>
<UL>
<LI><a href="#Getdashboards">GET Dashboards</a></LI>
</UL>
<LI><a href="#LookingForMore">Looking For More?</a>
</LI>
</UL>
Note: User and Role Management API is available on select plans. Site administrators can contact their Customer Success Manager for additional information.
<HR>
<a name="APIAuth"></a>
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 support@periscopedata.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>
Note: The User Management API needs to be enabled on a given site for the endpoints to work. Otherwise, it will provide a 404 response.
<a href="#top">Back to top</a>
<hr>
User Management API
<a name="GetUsers"></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>
}<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
<a href="#top">Back to top</a>
<a name="GetSingleUser"></a>
GET Single User
<div>
<table>
<thead>
<tr>
<th style="width:200px;text-align:left">URL</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>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 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>
}
</small></code>
</td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="CreateUser"></a>
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/v2/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>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>
</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>
}</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>
}</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>
}
</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
<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/{userid}
</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
</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> </tr> </thead>
<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>
</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>}</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>}</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> "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>}</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="DeleteUser"></a>
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/v2/users/{userid}
</td>
<td>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>404 if the the user id does NOT exist for the site</td> </tr> </tbody>
</table>
</div>
Request Body
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left">
<td><code><small>{}</small></code></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>
<a href="#top">Back to top</a>
<HR>
Role Management API
<a name="Getroles"></a>
GET Roles
<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/roles</td>
<td>
next_page_start=
<string>
(Optional)
<br> name=<name> (Optional)
</td>
<td>GET</td>
<td>200 if roles 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> "next_page_start": None,
<br> "total_roles": 2,
<br> "roles_this_page": 2,
<br> "roles": [
<br> {
<br> "id": "1000-Admin-123-User-id",
<br> "name": "Admin",
<br> "description": "App administrators",
<br> "is_custom": False,
<br> "privilges": [{
<br> "object_type": "AdminAccess",
<br> "permissions": ["view_cached_tables",
<br> "manage_databases"...]
<br> }
<br> ],
<br> "permissions": [ {
<br> "object_type": "Dashboard",
<br> "object_id": "abc-123-dashboard-456-id",
<br> "permissions": ["edit_dashboard_official_status"]
<br> }
<br> ]
<br> }
<br> ]
<br>}</small></code></td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="GetSinglerole"></a>
GET Single Role
<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">Response Codes</th>
</tr>
</thead>
<tbody>
<tr>
<td>/api/v1/roles/{id}</td>
<td>GET</td>
<td>200 if role_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 role_ id 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> "id": "Administrators",
<br> "name": "Admin",
<br> "description": "App Administrators",
<br> "is_custom": False,
<br> "privileges": [ {
<br> "object_type": "AdminAccess",
<br> "permissions": ["view_cached_tables",
<br> "manage_databases"...]
<br> }
<br> ],
<br> "permissions": [ {
<br> "object_type": "Dashboard",
<br> "object_id": "abc-123-dashboard-456-id",
<br> "permissions": ["edit_dashboard_official_status"]
<br> }
<br> ]
<br>}</small></code></td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="Createrole"></a>
CREATE Role
<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/roles/</td>
<td><b>OPTIONAL PARAMETER</b><br>?test_mode=true <br><br>If this parameter is set, then ONLY VALIDATIONS run and the actual role does NOT get created</td>
<td>POST</td>
<td>201 if role 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 name of the role is a system role name: Everyone, Admin, Analyst, Business User, Read<br><br>409 if the role name 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>name</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>New role name.</td>
</tr>
<tr>
<td><code><small>description</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>New role description.</td>
</tr>
<tr>
<td><code><small>create_by_email</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>role creator email address.</td>
</tr>
<tr>
<td><code><small>Privileges</code></small></td>
<td><code><small><b>Array</b></code></small></td>
<td><i>Required</i></td>
<td>New role privelges.</td>
</tr>
<tr>
<td><code><small>Permissions</code></small></td>
<td><code><small><b>Array</b></code></small></td>
<td><i>Required</i></td>
<td>New role dashboard permissions.</td>
</tr>
</tbody>
</table>
</div>
Request Body
<div>
<table>
<tbody>
<tr>
<td><code><small>{
<br> "name": <b><i>string</i></b>,
<br> "description": <b><i>string</i></b>,
<br> "created_by_email": <b><i>string</i></b>,
<br> "privileges":[{
<br> "object_type":"Dashboard",
<br> "permissions":["read_dashboards","create_dashboards"...]
<br> }],
<br> "permissions": [ {
<br> "object_type": "Dashboard",
<br> "object_id": "id",
<br> "permissions": ["create_sql_charts"]
<br> }]
<br>}</code></small></td>
</tr>
</tbody>
</table>
</div>
Example Request Body
<div>
<table>
<tbody>
<tr>
<td><code><small>{
<br> "name": "Friends",
<br> "description": "All the Friends"
<br> “created_by_email”: “rachel@example.com”
<br> "privileges": [ {
<br> "object_type": "Dashboard",
<br> "permissions": ["read_dashboards", "create_dashboards"...]
<br> }
<br> ],
<br> "permissions": [ {
<br> "object_type": "Dashboard",
<br> "object_id": "10000-dashboard-id",
<br> "permissions": ["create_sql_charts"]
<br>}
<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": "0000-friends-11111-id"
<br> "name": "Friends",
<br> "description": "All the Friends"
<br> “created_by_email”: “rachel@example.com”
<br> "privileges": [ {
<br> "object_type": "Dashboard",
<br> "permissions": ["read_dashboards", "create_dashboards"...]
<br> }
<br> ],
<br> "permissions": [ {
<br> "object_type": "Dashboard",
<br> "object_id": "10000-dashboard-id",
<br> "permissions": ["create_sql_charts"]
<br>}
<br>]
<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="Updaterole"></a>
UPDATE Role
<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/roles/{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 role 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 name of the role is any system role name: Everyone, Admin, Discovery, Busincess User, Read<br>
<br>400 if trying to update a default role other than Everyone role<br>
<br>400 if trying to rename Everyone role<br>
<br>400 if the role name 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>name</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>Update role name.</td>
</tr>
<tr>
<td><code><small>description</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Optional</i></td>
<td>Update role description.</td>
</tr>
<tr>
<td><code><small>updated_by_email</code></small></td>
<td><code><small><b>String</b></code></small></td>
<td><i>Required</i></td>
<td>The user updating the roles.</td>
</tr>
<tr>
<td><code><small>privileges</code></small></td>
<td><code><small><b>Array</b></code></small></td>
<td><i>Optional</i></td>
<td>Update role privilege(s).</td>
</tr>
<tr>
<td><code><small>permissions</code></small></td>
<td><code><small><b>Array</b></code></small></td>
<td><i>Optional</i></td>
<td>Update role dashboard permission(s).</td>
</tr>
</tbody>
</table>
</div>
Request Body
<div>
<table>
<tbody>
<tr>
<td><code><small>{
<br> "name": <b><i>string</i></b>,
<br> "description": <b><i>string</i></b>,
<br> “updated_by_email”: <b><i>string</i></b>,
<br> “privileges”: [<b><i>array</i></b>
<br> ],
<br> “permissions”: [<b><i>array</i></b>
<br> ]
<br>}</code></small></td>
</tr>
</tbody>
</table>
</div>
Example Request Body
<div>
<table>
<tbody>
<tr>
<td><code><small>{
<br> "name": Friends,
<br> "description": All the Friends,
<br> “updated_by_email”: “rachel@example.com”,
<br> is_custom: true,
<br> “privileges”: [{
<br> "object_type": "Dashboard",
<br> "permissions": ["read_dashboards", "create_dashboards"...]
<br> }
<br> ],
<br> “permissions”: [{
<br> "object_type": "Dashboard",
<br> "object_id": "id",
<br> "permissions": ["create_sql_charts"]
<br> }
<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": 0000-friends-11111-id", <br />
"name": Friends, <br />
"description": All the Friends, <br />
“updated_by_email”: “rachel@example.com”, <br />
"is_custom": true, <br />
“privileges”: [{ <br />
"object_type": "Dashboard", <br />
"permissions": ["read_dashboards", "create_dashboards"...] <br />
} <br />
], <br />
“permissions”: [{ <br />
"object_type": "Dashboard", <br />
"object_id": "id", <br />
"permissions": ["create_sql_charts"] <br />
} <br />
] <br />
}
</small>
</code>
</td>
</tr>
</tbody>
</table>
</div>
Some More Examples
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left">
<td>#updates only role name.<br><code><small>PUT { "name": "..." }</small></code></td>
</tr>
<tr style="width:300px;text-align:left">
<td>#updates only role description.<br><code><small>PUT { "description": "..." }</small></code></td>
</tr>
<tr style="width:300px;text-align:left">
<td>#updates both role name and access.<br><code><small>PUT { "name": "...", "base_permissions": "" }</small></code></td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="Deleterole"></a>
DELETE Role
<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/roles/{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 role 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 role does NOT EXIST</td>
</tr>
</tbody>
</table>
</div>
Request Body
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left">
<td><code><small>{
<br> “deleted_by_email”: <b><i>string</i></b>
<br>}</small></code></td>
</tr>
</tbody>
</table>
</div>
Example Response Body
<div>
<table>
<tbody>
<tr style="width:300px;text-align:left">
<td>
<code><small>{ <br> "message": "role removed from example-site" <br>}</small></code>
</td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="LookingForMore"></a>
Dashboard API
<a name="Getdashboards"></a>
GET 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/v1/dashboards</td>
<td>next_page_start=<string> (Optional)</td>
<td>GET</td>
<td>200 if dashboard 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>
"next_page_start": None,<br>
"total_items": 1,<br>
"items_this_page": 1,<br>
"dashboards": [<br>
{<br>
"id": "0000-dashboard-1111-id",<br>
"name": "Friends Dashboard",<br>
"description": "My Dashboard Description"<br>
}<br>
]<br>
}</small></code>
</td>
</tr>
</tbody>
</table>
</div>
<a href="#top">Back to top</a>
<a name="LookingForMore"></a>
Looking for More?
Refer to our community for examples on implementing the above API calls
<a href="#top">Back to top</a>
