Device Request API


These are advanced APIs. Most developers should utilize Ionic’s SDK to perform device request communication, such as for creating keys, requesting keys, and similar.

These API requests are used by an end-user device to communicate with and other services behind it, such as the Enterprise Tier’s Key Services for a customer.

In addition to the HTTPS transport security between the user’s device and’s servers, these APIs have additional layers of security as part of the request and response body formats. One benefit of this is that data can be securely transferred through any TLS-breaking man-in-the-middle proxy.

Additional security measures are used in certain request and response types to allow the transfer of data between the Key Appliance and the user’s device without or any other service or attacker learning the contents of those messages. This is possible due to keys which are part of the Secure Enrollment Profile (SEP), which is securely formed during enrollment.

NOTE: Although the SEP can be obtained via any method to use with these APIs, typically developers directly using these APIs enroll using the Server Enrollment Tool method, or in advanced cases directly call the Enrollment API.

High Level Description of Format

Most requests made by a device to secured under a Secure Enrollment Profile (SEP) follow the same basic format. (An exception is enrollment, which has its own unique format.)

All requests must have a Conversation ID that is unique to the request. These requests contain an “envelope” which is encrypted under the user’s SEP key between the user and This key is used in AES-GCM mode, and takes plaintext of the message which is then encrypted and placed inside the envelope. Since JSON can’t accept binary data, the encrypted output is encoded in Base64 encoding.

Typically the device picks an SEP to use based on the data being encrypted, the keytag and keyspace of the key(s) being fetched, application context, or user-driven actions (such as selecting from a list).

As a reminder, the Ionic SDKs implement this format and allow developers easy access to the functionality provided by these APIs. To develop directly against these APIs, without using the SDK, you should understand how general device requests are created and how responses should be parsed and validated. See Device Request API Format to learn more.

Available APIs

The following APIs follow the general device request format, with the exception of enrollment, which is used to obtain a SEP to be used in the making the other calls.

Action Description Resource Documentation
Enrollment The final step in the enrollment process that creates a Secure Enrollment Profile (SEP) for authenticated and authorized users. v2.3/register/{keyspace} Enrollment
Create keys Create unique keys used for encrypting individual pieces of data. v2.3/keys/create Data key creation
Fetch keys Fetch keys used for encrypting individual pieces of data. v2.3/keys/fetch Data key fetch
Fetch resources Retrieves named resources stored in for generalized device use (see documentation for more detail). v2.3/resources