Managing JWT and Role Token

Authorization Options

JWT Token

This authorization type uses a JWT token that the application passes to the SDK. The token is added to the header of every request.

JWT (JSON Web Token) is a JSON-formatted string containing claims signed to verify authenticity and integrity.

The token is generated and signed with an encryption key on the client server side (encryption keys are not stored in the application). When requested by the SDK, the application must provide the JWT token received from the server.

Advantages:

• Increased security of API requests.
• Ability to search profiles using any identifiers (email, phone number, custom ID).
• Support for multiple users on one device.
• Restoring access to a profile after reinstalling the application.
• Identification of a specific profile across different devices.

rToken

An alternative authorization method uses a role token (rToken) passed in the SDK configuration parameters. With this method, requests include a header containing the role token.

Characteristics:

• Profile search is only possible using the device push token (e.g. FCM).
• If the push token changes and is not sent to the server (for example, after app deletion and reinstallation), the link to the profile is lost and a new profile is created.

Limitations:

• Loss of profile linkage if the push token changes and is not registered on the Altcraft server.
• No ability to use the application for different profiles on the same device.
• No ability to register the same user on another device.

Configuring the Role Token and JWT Issuing Service

After creating a resource, the token management section becomes available in its settings:

To create a role token, you do not need to provide a public key. Simply specify its name, expiration date, and the associated profile database:

The role token acts as an access key for mSDK to the specific "resource–database" link. With this authorization type, the following operations in the platform become available:

• Event registration
• Profile field updates
• Profile import

To create a JWT token, a public key is required. The platform supports the ES384 algorithm (ECDSA as the most reliable option), but RS256, ES256, and ES512 can also be used for compatibility with different application libraries.

Key generation

Example of generating a key using ES384: openssl ecparam -name secp384r1 -genkey -noout -out private.ec.key openssl ec -in private.ec.key -pubout -out public.pem This generates private and public key files. The public key is used in the platform.

After the token is created, it can be copied and used further:

Authorizing mSDK Requests with a Role Token

When used for authorization, rToken grants access to operations within a specific resource. Due to its open format and immutable nature, restrictions are introduced on the type of profile matching available.

With a role token, profiles are searched using query parameters. In the current implementation, the backend expects the following query parameters when using rToken:

• provider — mobile push provider
• subscription_id — device token provided by the provider

The search for a profile is done by subscription identifier within the databases linked to the resource.

Characteristics

• Profile search is possible only by the device push token (e.g. FCM).
• When importing a profile via push subscription, it is marked as "temporary".
• When registering mobile events, linking events to a profile (writing to the event history) is not possible.
• If the push token changes and is not sent to the server, the link to the profile is lost and a new profile is created.

Usage

When using the Altcraft SDK, the token is passed as the rToken parameter of the AltcraftConfiguration class.

The library later includes it in the authorization header.

Authorizing mSDK Requests with a JWT Token

For secure authorization in the platform, it is recommended to use a JWT token. The token must be signed with the paired key previously added during token creation.

Characteristics

• Increased security of API requests. JWT acts as a protective wrapper for the role token, preventing unauthorized actions. The role token is embedded into the JWT payload, and only with the keys previously provided in the resource settings the platform authorizes mSDK actions.
• Ability to search profiles by any identifiers (email, phone number, custom ID), according to the matching rules.
• Support for multiple users on one device.
• Identification of a specific profile on different devices.
• Restoration of access to a profile after reinstalling the application.

Usage

The platform expects the following JWT payload structure:

{ 
  "iss": "<App Name>", 
  "exp": <UnixTimeUTC>, 
  "rtoken": "<RoleToken>", 
  "matching": "JSONString" 
}

• iss — issuer — unique identifier of the token issuer
• exp — expiration time — UNIX timestamp in seconds
• rtoken — the role token obtained during resource configuration
• matching — JSONString — a serialized object composed according to the documentation, for example: {"db_id":2,"email":"registered_db@localhost","matching":"email_profile"}

When using the Altcraft SDK, the token is passed as an implementation of the JWTInterface. The library later includes it in the authorization header.

Example of a final JWT: