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> is always granted.</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. This parameter is set to <code><small>["workbooks"]</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>    "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: &lt;EMAIL_ADDRESS &gt;</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>

Our support team is ready to help