REST API guide
Introduction
The Encap REST API is used to integrate client systems with the Encap server in order to perform mobile authentication of customers with designated mobile applications that integrate the Encap mobile authentication API.
Operations provided by the API are divided into two categories:
- Service provider API: This supports actions for enrolments, authentications, device management, application management and statistics.
- Admin API: This supports server administrators that should have full access to the Encap server and manage resources that are shared between organisations.
Documentation
Service provider API documentation
The Encap REST API documentation is available as part of the distribution on a running Encap instance. To find this, go to the URL <local_encap_url>/api/docs/index.html.
You can also look at the documentation for the latest Encap release on our public test server.
Admin API documentation
The Encap Admin REST API documentation is available as part of the distribution on a running Encap instance. To find this, go to the URL <local_encap_url>/admin-api/docs/index.html.
You can also look at the documentation for the latest Encap release on our public test server.
Suppress event callbacks for device operations
Some device management operations can trigger event callbacks when the application configuration subscribes to the relevant event. You can suppress the event callback for a single REST operation by adding the optional query parameter suppressEventCallback=true.
By default, suppressEventCallback is false, so existing integrations continue to receive event callbacks. This parameter only affects event callbacks for the REST operation where it is set. It does not affect on-demand callbacks for activation or authentication sessions.
The parameter is supported by the following service provider API endpoints:
| Operation | Endpoint | Suppressed event callback |
|---|---|---|
| Lock device | POST /api/smart-device/v1/devices/{deviceId}/lock | DEVICE_LOCKED |
| Unlock device | DELETE /api/smart-device/v1/devices/{deviceId}/lock | DEVICE_UNLOCKED |
| Deactivate device | DELETE /api/smart-device/v1/devices/{deviceId} | DEVICE_DEACTIVATED |
| Lock registrations by device hash | POST /api/smart-device/v1/devices/deviceHashes/{deviceHash}/lock | DEVICE_LOCKED for each locked registration |
Getting started
Authentication for REST API calls is to handled using Basic Authentication.
This authentication is not the same as the authentication service.
- All requests are required to have an authorisation header containing a Basic Authentication string.
- The Basic Authentication should have the API key ID as the username, and the API key secret as password.
- API key provisioning is handled by the Encap server administrator.
To learn how to set up the authentications keys, see the Generate API keys for REST authentication section on our Server configuration page.