> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For full documentation content, see https://docs.vapi.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# JWT Authentication

This documentation provides an overview of JWT (JSON Web Token) Authentication and demonstrates how to generate a JWT token and use it to authenticate API requests securely.

## Prerequisites

Before you proceed, ensure you have the following:

* An environment that supports JWT generation and API calls (e.g., a programming language or framework)
* An account with a service that requires JWT authentication
* Environment variables set up for the necessary credentials (e.g., organization ID and private key, both can be found in your Vapi portal)

## Generating a JWT Token

The following steps outline how to generate a JWT token:

1. **Define the Payload**: The payload contains the data you want to include in the token. In this case, it includes an `orgId`.
2. **Get the Private Key**: The private key (provided by Vapi) is used to sign the token. Ensure it is securely stored, often in environment variables.
3. **Set Token Options**: Define options for the token, such as the expiration time (`expiresIn`).
4. **Generate the Token**: Use a JWT library or built-in functionality to generate the token with the payload, key, and options.

### JWT Token Scopes

The generated JWT token can have one of two scopes: `private` or `public`. The scope of the token will determine the actions that can be performed using the token.

For example, it can be used to restrict which API endpoints the token can access.

As of writing, the only publicly scoped API endpoint is
[https://api.vapi.ai/call/web](https://api.vapi.ai/call/web), which is used for Web Call creation. All other
endpoints are privately scoped.

### Example (generating a private JWT token)

```js
// Define the payload
const payload = {
  orgId: process.env.ORG_ID,
  token: {
    // This is the scope of the token
    tag: "private",
  },
};

// Get the private key from environment variables
const key = process.env.PRIVATE_KEY;

// Define token options
const options = {
  expiresIn: "1h",
};

// Generate the token using a JWT library or built-in functionality
const token = generateJWT(payload, key, options);
```

### Example (generating a public JWT token)

```js
// Define the payload
const payload = {
  orgId: process.env.ORG_ID,
  // This is the scope of the token
  token: {
    tag: "public",
    restrictions: {
      enabled: true,
      allowedOrigins: ["https://example.vapi.ai"],
      allowedAssistantIds: ["1cbf8c70-5fd7-4f61-a220-376ab35be1b0"],
      allowTransientAssistant: false,
    },
  },
};

// Get the private key from environment variables
const key = process.env.PRIVATE_KEY;

// Define token options
const options = {
  expiresIn: "1h",
};

// Generate the token using a JWT library or built-in functionality
const token = generateJWT(payload, key, options);
```

### Explanation

* **Payload**: The payload includes the `orgId` representing the organization ID and the `token` object with the scope of the token.
* **Key**: The private key is used to sign the token, ensuring its authenticity.
* **Options**: The `expiresIn` option specifies that the token will expire in 1 hour.
* **Token Generation**: The `generateJWT` function (a placeholder for the actual JWT generation method) creates the token using the provided payload, key, and options.

## Usage (Making an Authenticated API Request)

If you set the scope to `private`, you can use it to make authenticated API requests. The following steps outline how to make an authenticated request:

1. **Define the API Endpoint**: Specify the URL of the API you want to call.
2. **Set the Headers**: Include the `Content-Type` and `Authorization` headers in your request. The `Authorization` header should include the generated JWT token prefixed with `Bearer`.
3. **Make the API Call**: Use an appropriate method to send the request and handle the response.

### Example

```js
async function getAssistants() {
  const response = await fetch("https://api.vapi.ai/assistant", {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
  });

  const data = await response.json();
  console.log(data);
}

fetchData().catch(console.error);
```

### Explanation

* **API Endpoint**: The URL of the API you want to call.
* **Headers**: The `Content-Type` is set to `application/json`, and the `Authorization` header includes the generated JWT token.
* **API Call**: The `fetchData` function makes an asynchronous GET request to the specified API endpoint and logs the response.

### Usage (Web Client)

If you set the scope to `public`, you can use it to make authenticated API requests using the Vapi Web Client.

```
import Vapi from '@vapi-ai/web';

const vapi = new Vapi('your-jwt-token');

vapi.start('your-assistant-id');
```