Authentication

📘 Some mobile SDKs still use workspace key and workspace secret authentication.

SuprSend client SDKs use public API Keys to authenticate requests. You can find Public Keys in SuprSend Dashboard -> Developers -> API Keys -> Public Keys. You can generate new ones and delete or rotate existing keys.

For production workspaces public API Keys alone isn’t enough as they are insecure. To solve this enable enhanced secure mode switch which you can find beside Public Key (shown in above image). This mandates signed user token (a JWT token that identifies the user that is performing the request) to be sent along with client requests.

Enhanced Security Mode with signed User Token

When enhanced security mode is on, user level authentication is performed for all requests. This is recommended for Production workspaces. All requests will be rejected by SuprSend if enhanced security mode is on and signed user token is not provided. This signed user token should be generated by your backend application and should be passed to your client.

Generate Signing Key

You can generate Signing key from SuprSend Dashboard (below Public Keys section in API Keys page).

Once signing key is generated it won’t be shown again, so copy and store it securely. It contains 2 formats: (i.) Base64 format: This is single line text, suitable for storing as an environment variable. (ii.) PEM format: This is multiline text format string.You can use any of the above format. This key will be used as secret to generate JWT token as shown in below step.

Creating Signed User JWT Token

This should be created on your backend application only. You will need to sign the JWT token with the signing key from above step and expose this JWT token to your Frontend application.

JWT Algorithm:ES256
JWT Secret:Signing key in PEM format generated in step1. If you are using Base64 format, it should be converted in to PEM format.
JWT Payload:

{
  "entity_type": 'subscriber', // hardcode this value to subscriber
  "entity_id": your_distinct_id, // replace this with your actual distinct id
  "exp": 1725814228, // token expiry unix epoch in seconds
  "iat": 1725814228 // token issued unix epoch in seconds.
  "scope": { "tenant_id": string[] }
}

If your workspace uses multiple tenants, use scope.tenant_id to restrict user access to specific tenants. Pass an array of tenant_id’s to allow only those tenants, or ["*"] to allow all of them.If you omit scope or set it to null, inbox and preferences fall back to the default tenant, while other features like events and user methods use the null scope as-is.

Note: If you pass tenant_id in scope, you must also pass tenant_id in the identify method of every SuprSend SDK, else all SDK API calls throw a scoping error.

Create JWT token using above information:

import jwt from 'jsonwebtoken';

const payload  = { entity_type:'subscriber', entity_id:"johndoe", exp:1725814228 };

const secret = 'your PEM format signing key';

// if base64 signing key format is used use below code to convert to PEM format.
const secret = Buffer.from('your_base64_signingKey', 'base64').toString('utf-8')

const signedUserToken = jwt.sign(payload, secret,{ algorithm: 'ES256' })

Using signed user token in client

After creating user token on backend send it to your Frontend application to be used in SuprSend SDK as user token.

import SuprSend from '@suprsend/web-sdk';

const suprSendClient = new SuprSend(publicApiKey: string);

const authResponse = await suprSendClient.identify(user.id, user.userToken);

Token expiry handling

To handle cases of token expiry our client SDK’s have Refresh User Token callback as parameter in identify method which gets called to get new user token when existing token is expired.

const authResponse = await suprSendClient.identify(user.id, user.userToken,
  { refreshUserToken: (oldUserToken, tokenPayload) => {
     //.... write your logic to get new token by making API call to your server...
     // return new token
  }});

⌘I

Developer Resources

Updates and Versioning

Security

SDKs and APIs

Features

Testing

Monitoring and Logging

Authentication

Enhanced Security Mode with signed User Token

Token expiry handling

​Enhanced Security Mode with signed User Token

​Token expiry handling

Enhanced Security Mode with signed User Token

Token expiry handling