# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://firstoken.gitbook.io/api-docs/guides/implementing-captures-sdk-js/jwt-authentication-for-firstoken-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.