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 Ionic.com 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 Ionic.com’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 Ionic.com 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 registration.

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

High Level Description of Format

Most requests made by a device to Ionic.com secured under a Secure Enrollment Profile (SEP) follow the same basic format. (An exception is registration, 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 Ionic.com. 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 registration, which is used to obtain a SEP to be used in the making the other calls.

Action Description Resource Documentation
Registration The final step in the enrollment process that creates a Secure Enrollment Profile (SEP) for authenticated and authorized users. v2.3/register/{keyspace} Registration
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 Ionic.com for generalized device use (see documentation for more detail). v2.3/resources