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

Setup JWT

JWT provides security between SDK and Gateway communication.

imiconnect allows you to configure a secret key while creating a mobile/web app asset to be used for JWT authentication.

Enabling JWT Authentication for Thread, Topic, and Segment APIs

As a security best practice, we recommend that you use JWT authentication for in-app messaging and for Thread, Topic, and Segment APIs. 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 need to enable the JWT authentication option on the mobile/web app asset configuration page.

  • SDK will provide the method to set the JWT from APP.
  • SDK should send the JWT token for each API request if JWT is enabled.
  • Gateway accepts the request and validates the JWT token against JWT secret Key. If it is valid then forward the request to process, else the request is rejected with an error code

JWT payload should contain the expiration (optional) and either 'appUserId or 'customerId.' In JWT payload client can add any other public or private claims. JWT signature should be generated using the SHA256 algorithm only. Examples of Header and Payload are provided below.

Sample information to generate a JWT token.

JWT Token Header:

  "alg": "HS256",
  "typ": "JWT"

JWT Payload:

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

JWT Token Signature:

  base64UrlEncode(header) + "." +

Sample JWT token


Below needs to be ensured before generating JWT:

  • 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).

  • While using, client must select the 'secret base64 encode' checkbox on the UI if they are using the base64 encoded secret key to generate the token.

SDK uses this JWT token as part of the header (Authorization) for all API requests, Find an example below.

URL :{appid}/setuserid

Headers: Authorization: Bearer <token>

"clientId" : "AP09092338/2315/v2_22315c49b793ad39",
"userId" : "2315"

App creation

On app creation, app profiles API accepts the payload (including jwt_secretkey) from IMIconnect and it will be stored in mongo (apps collection)

Validating JWT token using SDK API request

  1. When SDK invokes the gateway API, It accepts the request from SDK with JWT token specified in the Authorisation header.
  2. It extracts the appId from the request and loads the app information. Then it gets the JWT secret Key configured in the app.
  3. A request is validated for that JWT token with that of secret Key.
  4. If resulted that the token is valid then it will be forwarded for further processing.
  5. It will be validated with appId, userid/customerid against payload extracted from JW, else rejected with an error code.

The response format is as follows:

  “status”:”Invalid token” 

Error codes and format

38 - Invalid token
39 - Token is required to access the requested resource.
40 - Token imiconnect

Updated about a month ago

Setup JWT

JWT provides security between SDK and Gateway communication.

Suggested Edits are limited on API Reference Pages

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