JWT Authentication for Firstoken SDK

JWT (JSON Web Token) authentication provides enhanced security for your Firstoken SDK implementation. This feature is optional and designed for high-security environments.

This section explains how to generate a JWT token for authenticating requests to Firstoken using the SDK. The JWT token is used to verify the identity of the external application and authorize access to specific routes.

Prerequisites

1. External Application in Firstoken Console Before generating the JWT token, you need to create an External Application in the Firstoken console:

   1. Access the Firstoken console

   2. Navigate to Applications

   3. Create a new External Application

   4. Important: Ensure the application has the "Allow Inbound Requests" permission enabled

   5. Copy the Secret Key ID of the External Application (this will be your signingKey)

   6. On External Applications table copy the UUID of the column "ID" (this will be your externalAppId)

2. Inbound Route

   1. In the Firstoken console, create an Inbound Route

   2. Copy the generated ID for the route (this will be your routeId)

Implementation

The code below shows a Node.js example to illustrate the generation of the JWT. You must replace the signingKey field with a valid SECRET code provided by Firstoken in the onboarding and account setup process. If you do not have a SECRET code yet, please contact your representative agent to complete the setup process.

const jwt = require("jsonwebtoken");

const claims = {
    externalAppId: externalAppId,
    routeId: routeId,
    origin: "https://example.com"
};

const token = jwt.sign(claims, signingKey, { expiresIn: "10m" });

Required Parameters

externalAppId - Required

• Type: String (UUID)

• Description: The identifier of your External Application created in Firstoken

routeId - Required

• Type: String

• Description: The identifier of the Inbound Route that will be used to process the request

origin - Required

• Type: String (URL)

• Description: The origin is the URL of the client making the request

exp- Required

• Type: String

• Description: Token expiration time

signingKey - Required

• Type: String (Secret)

• Description: Secret key for signing the JWT token

Complete Example

const jwt = require("jsonwebtoken");

// Configuration (obtain these values from the Firstoken console)
const externalAppId = "550e8400-e29b-41d4-a716-446655440000";
const routeId = "TEST123456";
const origin = "https://my-application.com";
const signingKey = "your-signing-key-secret";

// Generate the token
const claims = {
    externalAppId: externalAppId,
    routeId: routeId,
    origin: origin
};

const token = jwt.sign(claims, signingKey, { expiresIn: "10m" });

console.log("Generated JWT token:", token);

Security Considerations

• Never expose the signingKey in client-side code

• Use HTTPS for all communications

• Validate the origin on the server to prevent CSRF attacks

• Keep short expiration times for JWT tokens

• Rotate keys periodically