imiconnect Developer Hub

Welcome to the imiconnect developer hub. You'll find all the resources to help you get started with imiconnect quickly. We are here to support you if you get stuck. Let's jump right in!

Get Started    API Reference

JWT Authentication

JSON Web Tokens (JWT) provides additional, token based, security for our Core SDK and Web APIs.

imiconnect supports the use of JWT within the Core SDK and Thread, Topic and Segment APIs. JWT provides additional security by providing a mechanism to restrict resource access to authorized users.

For detailed information on JWT please jwt.io where you will find a very good introduction.

Note that imiconnect only currently supports the SHA256 algorithm which uses a pre-shared secret key. The key is configured during creation of a mobile/web app asset within the imiconnect platform.

Enabling JWT Authentication for Thread, Topic, and Segment APIs

As a security best practice, we recommend that you enable JWT authentication. It is an optional feature and is not enabled by default. Please send an email to [email protected] to enable JWT authentication for Thread, Topic, and Segment APIs for your tenant if you'd like to use it. Once it's been enabled by the Operations team, you will need to enable the JWT authentication option on the mobile/web app asset configuration page.

Token Format.

JWT Token Header

The following table lists the supported header attributes:

Attribute
Value
Notes

alg

HS256

Specifies the signing algorithm used, imiconnect currently only supports HS256.

typ

JWT

The token type, always JWT.

Example Token Header

{
  "alg": "HS256",
  "typ": "JWT"
}

Token Payload

The following table lists the JWT claims which are supported within the token payload:

Claim
Example Value
Notes

exp

1584525821

Optional - This claim specifies the expiration time of the token expressed as seconds since the epoch. Although imiconnect does not enforce a maximum duration it is best practice to keep this as short a duration as possible for your use case.

appId

TR21063826

Mandatory - This claim must be set to the
id of your app asset as configured within the imiconnect tenant portal. This will be validated before requests are serviced.

userId

67deb017-5038-4832-a6b9-aa7e00987b6f

Optional - When specified this claim must match the id of the user within imiconnect and, if the resource being accessed is user centric, the value will be validated before requests are serviced. User ids are an arbitrary string value assigned to an app / device profile during SDK registration.

customerId

23bcd542-1562-7431-c329-ca54ae111c31

Optional - When specified the value of this claim must match the id of the customer profile. This attribute is only validated when performing linking / unlinking with a customer profile. See updateProfileData [updateDeviceProfileParam](https://developers.imiconnect.io/docs/ios-sdk-core#section-update-device-profile-param].

Example Payload

{
  "exp": 1584525821,
  "appId": "TR21063826",
  "userId": "67deb017-5038-4832-a6b9-aa7e00987b6f"
}

JWT Token Signature

The following example demonstrates how a signature is generated:

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

Sample JWT token

NOTE

  • The secret key must be base64 encoded before entering in the app asset configuration page.
    • The length of the secret key before encoding must be at least 256 bits (32 bytes).

JWT validation errors

If an SDK method call fails because of a JWT validation error then an exception is generated with one of the following error codes:

ICErrorCode enum
Ordinal Value
Description

TokenInvalid

38

The provided token is invalid, check that the token has been generated using the correct format and contains valid data.

TokenRequired

39

A token is expected but is missing.

TokenExpired

40

The token has expired.

Updated 3 months ago

JWT Authentication


JSON Web Tokens (JWT) provides additional, token based, security for our Core SDK and Web APIs.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.