Sentry Identity Server - Admin API Reference

Overview

This document lists the various APIs currently available in the Sentry Identity Administration server.

Enabling API Access

All Admin APIs require a Client ID and secret credentials of a Client application that is provisioned for API access in the Admin Console.

How to

1. Login to the Admin console and switch to the API Access tab on the left menu
2. Search for and select the Client 
3. Use the switch to enable API Access to this client

Accessing API

There are two ways to access the APIs:

Credentialed API

Client credentials are sent with the API in the HTTP header directly using the following keys:

X-CLIENT-ID: the Client ID
X-CLIENT-SECRET: the Client secret

Bearer Token

A Bearer Token issued by Sentry Identity Server using the Client credentials is added to the HTTP Header

How to

Send a POST request to the OAuth access token endpoint: 
http(s)://<domain>/sentrygw/api/token

Parameters: 
    grant_type=client_credentials
    client_id=<client_id>
    client_secret=<client_secret>

The parameter grant_type=client_credentials notifies the endpoint that the Client Credentials flow is used.

This returns the access_token in the response from the token endpoint in a JSON object. This access token will be valid for a specified time (in seconds) in the expires_in field.

This access token is sent as a bearer token.

Client API

ADD New Client

Purpose: Add a new Client application

URL: http://<domain>/sentryadmin/api/public/client/add

Method: POST

Request Parameters:

Parameter Type Value Default Description
name String Required Name of the client
description String Optional Description for the client
url String Optional Client application URL
iconUrl String Optional Client icon URL (For best results with the installed HTML templates, the recommended size is 72 x 72 pixels.)
redirectURL String Required Redirect URL (callback URL) of the client
accessTokenExpireTime Integer Required 1 Time interval for access token expiry.
accessTokenExpireUnit String Required MINUTE Time unit to set the access token expire time. The available units are
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • YEAR
refreshTokenExpireTime Integer Required 1 Time interval for refresh token expiry.
refreshTokenExpireUnit String Required MONTH Time unit to set the refresh token expire time. The available units are
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • YEAR
authCodeExpireTime Integer Optional 2 Time interval for authorization code expiry.
authCodeExpireUnit String Optional MINUTE Time unit to set the authorization code expire time. The available units are
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • YEAR

Headers:

Parameter Type Description
X-CLIENT-ID String client_id of Client authorized for Admin API access
X-CLIENT-SECRET String client_secret of Client authorized for Admin API access

Response:

Parameter Type Description
status String Status of the REST call (Success/Failure)
message String Status message on the REST call.
result JSON JSON response

Validation Messages:

Condition Error code Description
If name is empty 400 Name is empty
If redirectURL is empty 400 Redirect URL is empty
If name already exist 409 Name already exists
If redirectURL already exists 409 Redirect URL already exists
Invalid redirectURL 400 Invalid Redirect URL
Invalid client 400 Invalid Client
if accessTokenExpireTime is empty 400 Access token expire time is empty
if accessTokenExpireUnit is empty 400 Access token expire unit is empty
If refreshTokenExpireTime is empty 400 Refresh token expire time is empty
If refreshTokenExpireUnit is empty 400 Refresh token expire unit is empty
if accessTokenExpireTime is invalid 400 Access token expire time is invalid
if accessTokenExpireUnit is invalid 400 Access token expire unit is invalid
If refreshTokenExpireTime is invalid 400 Refresh token expire time is invalid
If refreshTokenExpireUnit is invalid 400 Refresh token expire unit is invalid

Response:

Field Description
client_id Client id generated for the new client
client_secret Client secret generated for the new client

Example:

Request:

POST /api/public/client/add HTTP/1.1

Host: <domain>/sentryadmin
X-CLIENT-ID: ec738b56-b771-35f8-9d27-7f31a8d3eab
X-CLIENT-SECRET: xx-xxx-xx-xxx-xxx
Content-Type: application/json
{
"name": "demo client",
"description": "demo client description",
"url": "http://clienturl.com/testclient",
"redirectURL": "http:// clienturl.com/testclient/auth,
"accessTokenExpireTime": 1,
"accessTokenExpireUnit": "DAY",
"refreshTokenExpireTime": 1,
"refreshTokenExpireUnit":"MONTH"
}

Response:

 {
  "status": "Success",
  "message": "Client added successfully",
  "result": {
    "client\_secret": "6f8a5234-e89e-4867-9cd9-89025b5ab91e",
    "client\_id": "e6a94284-6bf5-35ec-9db2-91c753a6f1c0"
  }
}

UPDATE Client

Purpose: Update an existing client

URL: http://<domain>/sentryadmin/api/public/client/update

Method: POST

Request Parameters:

Parameter Type Value Default Description
clientId String Required Client id to edit a particular client
name String Required Name of the client.
redirectURL String Required Redirect URL of the client
accessTokenExpireTime Integer Required Time interval for access token expiry.
accessTokenExpireTime Integer Required 1 Time interval for access token expiry.
accessTokenExpireUnit String Required MINUTE Time unit to set the access token expire time. The available units are
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • YEAR
refreshTokenExpireTime Integer Required 1 Time interval for refresh token expiry.
refreshTokenExpireUnit String Required MONTH Time unit to set the refresh token expire time. The available units are
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • MONTH
  • YEAR

Headers:

Parameter Type Description
X-CLIENT-ID String client_id of Client authorized for Admin API access
X-CLIENT-SECRET String client_secret of Client authorized for Admin API access

Response:

Parameter Type Description
status String Status of the REST call (Success/Failure)
message String Status message on the REST call.
result JSON JSON string of the response object.

Validation Messages:

Condition Error code Description
If clientId is empty 400 Client id is empty
If clientId does not exist 400 Invalid Client id
If name is empty 400 Name is empty
If redirectURL is empty 400 Redirect URL is empty
If name already exist 409 Name already exists
If redirectURL already exists 409 Redirect URL already exists
Invalid redirectURL 400 Invalid Redirect URL
Invalid client 400 Invalid Client
if accessTokenExpireTime is empty 400 Access token expire time is empty
if accessTokenExpireUnit is empty 400 Access token expire unit is empty
If refreshTokenExpireTime is empty 400 Refresh token expire time is empty
If refreshTokenExpireUnit is empty 400 Refresh token expire unit is empty
if accessTokenExpireTime is invalid 400 Access token expire time is invalid
if accessTokenExpireUnit is invalid 400 Access token expire unit is invalid
If refreshTokenExpireTime is invalid 400 Refresh token expire time is invalid
If refreshTokenExpireUnit is invalid 400 Refresh token expire unit is invalid

Response:

Field Description
client_id Client id will used to authorize the client registered with the Sentry.
client_secret This is used to get the access_token,resource details along with client_id

Example:

Request:

POST /api/public/client/update HTTP/1.1

Host: <domain>/sentryadmin
X-CLIENT-ID: ec738b56-b771-35f8-9d27-7f31a8d3eab
X-CLIENT-SECRET: xx-xxx-xx-xxx-xxx
Content-Type: application/json

{
"clientId":"6f8a5234-e89e-4867-9cd9-89025b5ab91e",
"name": "demo client",
"redirectURL": "http://<domain>/foo/auth",
"accessTokenExpireTime": 1,
"accessTokenExpireUnit": "DAY",
"refreshTokenExpireTime": 1,
"refreshTokenExpireUnit": "MONTH"
}

Response:

{
 "status": "Success",
 "message": "Client updated successfully",
 "result": {
    "client_id": "e6a94284-6bf5-35ec-9db2-91c753a6f1c0",
    "client_secret": "6f8a5234-e89e-4867-9cd9-89025b5ab91e"
  }
}

DELETE Client

Purpose: Delete a list of clients

Note: This API call is logged to the audit log

URL: http://<domain>/sentryadmin/api/public/client/delete

Method: POST

Request Parameters:

Parameter Type Value Default Description
clientIds String Array Required client_id of clients to be deleted Array of Client IDs

Headers:

Parameter Type Description
X-CLIENT-ID String client_id of Client authorized for Admin API access
X-CLIENT-SECRET String client_secret of Client authorized for Admin API access

Response:

Field Type Description
status String Status of the REST call (Success/Failure)
message String Status message on the REST call.
result JSON JSON string of the response object.

Validation Messages:

Condition Error code Description
If client_id is invalid 400 Invalid client(s) - {clientIds}

Example:

Request:

POST /api/public/client/delete HTTP/1.1

Host: <domain>/sentryadmin
X-CLIENT-ID: ec738b56-b771-35f8-9d27-7f31a8d3eab
X-CLIENT-SECRET: xx-xxx-xx-xxx-xxx
Content-Type: application/json
{
"clientIds": ["14d90e49-15d8-3f76-9ec7-875127d6485e","7215ee9c-7d9d-3229-9292-1a40e899ec5f"]
}

Response:

{
  "status": "Success",
  "message": {1} Client(s) deleted successfully, {2} failed",
  "result" : {
    "success": ["14d90e49-15d8-3f76-9ec7-875127d6485e"],
    "failure": [{"client\_id": "7215ee9c-7d9d-3229-9292-1a40e899ec5f " , "error": "" }]
  }
}

User API

ADD or UPDATE User

Purpose: Add a New User or Update and existing User

If the user already exists in the database, then user will be updated with provided details.

Note: This API call is logged to the audit log

URL: http://<domain>/sentryadmin/api/public/user/addupdate

Method: POST

Request Parameters:

Parameter Type Value Description
username String Required E-mail id of the user
firstName String Required First name of the user
lastName String Required Last name of the user
telephone String Required User telephone number
roles String Array Required Assigning Sentry predefined roles i.e. SENTRY_ROLE_SUPER_ADMIN,SENTRY_ROLE_FIRM_ADMIN and SENTRY_ROLE_USER.
defaultClientId String Required Default client application client Id, user will be assigned to this client only if clientids array is empty.
clientIds String Array Optional client_ids of applications to which the user is to be assigned (allowed access)

Headers:

Parameter Type Description
X-CLIENT-ID String client_id of Client authorized for Admin API access
X-CLIENT-SECRET String client_secret of Client authorized for Admin API access

Response:

Field Type Description
status String Status of the REST call (Success/Failure)
message String Status message on the REST call.
result JSON JSON string of the response object.

Validation Messages:

Condition Error code Description
Invalid username 400 Username is not email address
Invalid client 400 Invalid Client
Invalid role 400 Invalid Role

Request:

POST /api/public/user/addupdate HTTP/1.1

Host: rivetlabs.com/sentryadmin
X-CLIENT-ID: ec738b56-b771-35f8-9d27-7f31a8d3eab
X-CLIENT-SECRET: \*\*\*-\*\*\*-\*\*\*-\*\*\*-\*\*\*
Content-Type: application/json
{
    "username":"demouser@xyz.com",
    "firstName":"demo-firstname",
    "lastName":"demo-lastname",
    "telephone":"(+1) 123-1234-12345",
    "roles":["SENTRY\_ROLE\_FIRM\_ADMIN", "SENTRY\_ROLE\_USER","INVALID\_ROLE\_TEST"],
    "defaultClientId":"ec738b56-122-35af8-9d27-tsafm45zdb"
}

Response:

 {
  "status": "Success",
  "message": "User added/updated successfully",
  "result": {
    "username": "demouser06",
    "assignedClientIds": ["clientid1", "clientid2"],
    "failedClientIds": [{"id":"clientid3","error":""}, {"id":"clientid4","error":""}],
    "assignedRoles": ["SENTRY\_ROLE\_FIRM\_ADMIN"],
    "failedRoles": [{"role": "ROLE\_TEST","error": "Role(s) does not exist"}]
  }
}

DELETE User

Purpose: Delete a list of Users

Note: This API call is logged to the audit log

URL: http://<domain>/sentryadmin/api/public/user/delete

Method: POST

Request Parameters:

Parameter Type Value Description
usernames String Array Required usernames of Users to be deleted

Headers:

Parameter Type Description
X-CLIENT-ID String client_id of Client authorized for Admin API access
X-CLIENT-SECRET String client_secret of Client authorized for Admin API access

Response:

Field Type Description
status String Status of the REST call (Success/Failure)
message String Status message on the REST call.
result JSON JSON string of the response object.

Validation Messages:

Condition Error code Description
If username (emailId) is invalid 400 Invalid username(s) - {usernames}

Example:

Request:

POST /api/public/user/delete HTTP/1.1

Host: rivetlabs.com/sentryadmin
X-CLIENT-ID: ec738b56-b771-35f8-9d27-7f31a8d3eab
X-CLIENT-SECRET: xx-xxx-xx-xxx-xxx
Content-Type: application/json
{
"usernames": ["demouser@xyz.com", "demouser1@xyz.com"]
}

Response:

{
    "status": "Success",
    "message": "{1} User(s) deleted successfully, {2} failed",
    "result" : {
      "success": ["demouser1@xyz.com", "demouser3@xyz.com"],
      "failure": [{"username": "demouser2@xyz.com" , "error": "" }]
    }
}

INVITE Users

Purpose: Send an e-mail invitation to an list of users

Note: This API call is logged to the audit log

URL: http://<domain>/sentryadmin/api/public/user/invite

Method: POST

Request Parameters:

Parameter Type Value Description
usernames String Array Required E-mail ids of users to be invited
clientId String Required Client application client Id
additionalMsg String Optional Additional message for the invitation mail body if required.

Headers:

Parameter Type Description
X-CLIENT-ID String client_id of Client authorized for Admin API access
X-CLIENT-SECRET String client_secret of Client authorized for Admin API access

Response:

Parameter Type Description
status String Status of the REST call (Success/Failure)
message String Status message on the REST call with count of success and failed email sends
result JSON JSON string of the response object.

Validation Messages:

Condition Error code Description
If username (emailId) is invalid 400 Invalid username(s) - {usernames}

Example:

Request: POST /api/public/user/invite HTTP/1.1

Host: rivetlabs.com/sentryadmin
X-CLIENT-ID: ec738b56-b771-35f8-9d27-7f31a8d3eab
X-CLIENT-SECRET: xx-xxx-xx-xxx-xxx
Content-Type: application/json
{
"usernames": ["demouser@xyz.com", "demouser1@xyz.com"]
}

**Response**:
```json
{
  "status": "Success",
  "message": "{1} Invitation(s) added to email queue successfully, {2} failed",
  "result" : {
    "success": ["demouser1@xyz.com", "demouser3@xyz.com"],
    "failure": [{"username": "demouser2@xyz.com" , "error": "" }]
  }
}

REVISION HISTORY

Date Author Changes Version
20 Oct 2016 Uttesh Kumar Initial Draft 1.0