> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/guides/implementing-captures-sdk-js/jwt-authentication-for-firstoken-sdk.md).

# 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.

```javascript
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

```javascript
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