REST API

The Mobile Gateway provides different APIs to manage the users and their enrollment info.

• Retrieving all security groups and their users
• Adding / Removing a user from a security group
• Generating an enrollment code for a given user
• Disenrolling a user from a single device or from all its devices

Deployment URL

URL of the mobile gateway depends on the deployment, but will typically be:

https://{hostname}/sense/secserver

Paths documented will be relative to this deployment base URL.

The APIs' base path correspond to a fixed "/api/rest" prefix, followed by the role that has access to the function (eg. "/provisioner").

The domain is implicitly defined by the user's authorization. Username must not include the domain (it is only provided in the EnrollmentInfo object since it should be encoded in a QRCode and scanned on the client which doesn't know the domain).

Authentication

All API described in this chapter are protected with HTTP Basic authentication. Credentials consist to the username and the password of a valid administrator account on the SENSE server.

References

Get all users

GET /api/rest/provisioner/users?enrollmentCodeExpirationTimeAfter={enrollmentCodeExpirationTimeAfter}&enrollmentCodeExpirationTimeBefore={enrollmentCodeExpirationTimeBefore}

PATH VARIABLES

RESPONSE

[ { "username" : "username",  "enrollmentInfo" : null }, { "username" : "username2", "enrollmentInfo" : { "code" : "XF45-F29Z", ... }, ... ]

RESPONSE STATUS CODE

Get a single user

GET /api/rest/provisioner/users/{username}

PATH VARIABLES

RESPONSE

{ "username" : "username", "enrollmentInfo" : { "code" : "XF45-F29Z", "validUntil": 1521767010211, "serverUrl" : "https://server/sense/appserver/Server", "username" : "username@domain" } }

RESPONSE STATUS CODE

Get all groups

GET /api/rest/admin/groups

RESPONSE

[ { "id" : "26088441-82ad-4db0-8a4d-d67fdbc6fc98",  "name" : "My users" }, { "id" : ... }, ... ]

RESPONSE STATUS CODE

Add a single user

POST /api/rest/admin/users

BODY

{ "username" : "username", "groupId" : "26088441-82ad-4db0-8a4d-d67fdbc6fc98" }

DETAILS

RESPONSE STATUS CODE

Delete a single user

DELETE /api/rest/admin/users/{username}

PATH VARIABLES

RESPONSE STATUS CODE

Enable enrollment for a user

PATCH /api/rest/provisioner/users/{username}

API is also reachable with POST method by adding an extra HTTP header X-HTTP-Method-Override: PATCH.

PATH VARIABLES

BODY

{ "enrollmentInProgress" : true }

RESPONSE

{ "username" : "username", "enrollmentInfo" : { "code" : "XF45-F29Z", "validUntil": 1521767010211, "serverUrl" : "https://server/sense/appserver/Server", "username" : "username@domain" } }

RESPONSE STATUS CODE

Enrollment info as object

GET /api/rest/provisioner/users/{username}/enrollmentInfo

PATH VARIABLES

RESPONSE

{ "code" : "XF45-F29Z", "validUntil": 1521767010211, "serverUrl" : "https://server/sense/appserver/Server", "username": "username@domain" }

RESPONSE STATUS CODE

Enrollment info as QR Code PNG

GET /api/rest/provisioner/users/{username}/enrollmentInfo?format=QRCode&width={width}&height={height}

PATH VARIABLES

RESPONSE

RESPONSE STATUS CODE

Disable enrollment

PATCH /api/rest/provisioner/users/{username}

API is also reachable with POST method by adding an extra HTTP header X-HTTP-Method-Override: PATCH.

PATH VARIABLES

BODY

{ "enrollmentInProgress" : false }

RESPONSE

{ "enrollmentInfo" : null }

RESPONSE STATUS CODE

Get all enrollment data for a given user

GET /api/rest/provisioner/users/{username}/enrollmentData?creationTimeAfter={creationTimeAfter}&creationTimeBefore={creationTimeBefore}&mobileApplicationIdentifier={mobileApplicationIdentifier}

PATH VARIABLES

REQUEST PARAMETERS

REQUEST HEADERS

RESPONSE

[ { "id" : "1234abcd", "username" : "username", "creationTime" : 1484960610593, "deviceModel" : "samsung GT-I9505", "deviceName" : "Galaxy S4", "osVersion" : "5.0.1", "operatingSystem" : "ANDROID", "enabled" : true }, { "id" : "5678efgh", ... }, ... ]

RESPONSE STATUS CODE

Get all enrollment data

GET /api/rest/provisioner/enrollmentData?creationTimeAfter={creationTimeAfter}&creationTimeBefore={creationTimeBefore}&mobileApplicationIdentifier={mobileApplicationIdentifier}

REQUEST PARAMETERS

RESPONSE

RESPONSE STATUS CODE

Disenroll app

DELETE /api/rest/provisioner/users/{username}/enrollmentData/{id}

PATH VARIABLES

RESPONSE STATUS CODE

Disenroll all apps

DELETE /api/rest/provisioner/users/{username}/enrollmentData

PATH VARIABLES

RESPONSE STATUS CODE

Send a notification to all devices of the user

POST /api/rest/provisioner/users/{username}/notification

PATH VARIABLES

BODY

PushNotificationMessage

{
  "notificationTitle" : "notificationTitle", <1>
  "notificationBody" : "notificationBody", <2>
  "localizedNotificationTitleKey" : "localizedNotificationTitleKey", <3>
  "localizedNotificationTitleArgs" : ["arg1", "arg2"] <4>
  "localizedNotificationBodyKey": "localizedNotificationBodyKey" <5>
  "localizedNotificationBodyArgs": ["arg1", "arg2"] <6>
  "backgroundNotification" : false <7>
  "data": {"key1": "value1", "key2": "value2"} <8>
  "badge": 123456 <9>
}

1. The title of the notification
2. The body of the notification
3. The key for localized notification title
4. Arguments for localized notification title
5. The key for localized notification body
6. Arguments for localized notification body
7. Default false, specifies if the notification should be handled by the app itself
8. Additional data for the notification
9. Badge number for the notification

DETAILS

RESPONSE STATUS CODE

Send a notification to a specific user's device

POST /api/rest/provisioner/users/{username}/enrollmentData/{enrollmentDataId}/notification

PATH VARIABLES

BODY

PushNotificationMessage

{
  "notificationTitle" : "notificationTitle", <1>
  "notificationBody" : "notificationBody", <2>
  "localizedNotificationTitleKey" : "localizedNotificationTitleKey", <3>
  "localizedNotificationTitleArgs" : ["arg1", "arg2"] <4>
  "localizedNotificationBodyKey": "localizedNotificationBodyKey" <5>
  "localizedNotificationBodyArgs": ["arg1", "arg2"] <6>
  "backgroundNotification" : false <7>
  "data": {"key1": "value1", "key2": "value2"} <8>
  "badge": 123456 <9>
}

1. The title of the notification
2. The body of the notification
3. The key for localized notification title
4. Arguments for localized notification title
5. The key for localized notification body
6. Arguments for localized notification body
7. Default false, specifies if the notification should be handled by the app itself
8. Additional data for the notification
9. Badge number for the notification

DETAILS

RESPONSE STATUS CODE