How to Create Scoped API Tokens for Restricted Access

ChatBotKit API tokens grant access to the full API by default, but in many situations you want to limit what a token can do. Scoped tokens let you lock a token down to specific API routes so it can only be used for the exact operations you allow. This is especially useful when you need to share a token with a third-party service, embed it in a client-side application, or hand it off to an automation that should only perform a narrow set of actions.

In this tutorial you will learn how to:

• Create a scoped token from the ChatBotKit dashboard
• Understand the allowedRoutes configuration and glob patterns
• Scope a token to a single endpoint such as /v1/bot/{botId}/session/create
• Use pre-built token templates for common access patterns

Prerequisites

• A ChatBotKit account
• At least one bot created in your account (for the session creation example)

Why Use Scoped Tokens?

A standard API token has unrestricted access to every endpoint in the ChatBotKit API. This is convenient during development, but it poses a security risk in production. If the token is leaked or misused, an attacker could read, modify, or delete any resource in your account.

Scoped tokens follow the principle of least privilege: each token gets exactly the permissions it needs and nothing more. Common use cases include:

• Client-side session creation - a token that can only create bot sessions, safe to use from a backend endpoint exposed to the internet
• Monitoring dashboards - a token that can only fetch usage metrics
• Content pipelines - a token that can only manage datasets and files
• Read-only integrations - a token limited to list and fetch operations

Step 1: Navigate to Token Management

1. Log in to your ChatBotKit account at chatbotkit.com
2. Open the Tokens page from the developer tools at chatbotkit.com/tokens
3. Click Create Token

Step 2: Choose a Token Configuration Template

When creating a new token, you can choose from a set of pre-built configuration templates that cover common use cases. Each template pre-fills the allowedRoutes configuration with the right glob patterns.

Available templates include:

Select a template to get started quickly, or configure the allowed routes manually for more granular control.

Step 3: Understand the allowedRoutes Configuration

The allowedRoutes field is an array of glob patterns that define which API routes the token can access. Routes are matched against the path portion of the API URL, without the /v1/ prefix.

Glob Pattern Syntax

Examples

• bot/** - all bot-related endpoints (list, create, fetch, update, delete, sessions, etc.)
• bot/**/usage/fetch - usage fetch endpoint for any bot
• bot/abc123/session/create - session creation for one specific bot only
• conversation/** - all conversation endpoints
• **/list - all list endpoints across every resource type
• **/fetch - all fetch endpoints across every resource type

Step 4: Create a Token Scoped to Bot Session Creation

This is the most common use case: you have a backend endpoint that creates a conversation session for a specific bot, and you want the token to be usable only for that one operation.

1. On the Create Token page, give your token a descriptive name, for example Production Session Token - Support Bot
2. Select the Bot Session Create template, or manually enter the configuration
3. Replace <botId> with the actual ID of your bot

The configuration should look like this:

Replace YOUR_BOT_ID with your actual bot ID (e.g. clx1abc2def3ghi4jkl).

4. Click Create to generate the token
5. Copy the token value - it will only be shown once

This token can now be used in your backend to create sessions for that specific bot, but it cannot list bots, delete conversations, modify datasets, or access any other endpoint.

Step 5: Use the Scoped Token in Your Application

Here is how you would use the scoped token in a Next.js API route to create a bot session:

Store the scoped token in your environment variables:

If the token is used to call any other endpoint, the API will reject the request with a 403 Forbidden response.

Combining Multiple Routes

A scoped token can allow access to multiple routes. For example, to create a token that can both create sessions and fetch usage data for a specific bot:

Or to create a token that can manage all content-related resources:

Troubleshooting

Token returns 403 Forbidden

• Verify the route pattern in allowedRoutes matches the endpoint you are calling. Routes should not include the /v1/ prefix.
• Check for typos in bot IDs or resource IDs in the allowed routes.
• Confirm the glob pattern is correct - use ** for multi-segment wildcards.

Token works for some endpoints but not others

• Review your allowedRoutes list. Each endpoint you want to access must be covered by at least one pattern.
• Remember that bot/** covers all sub-paths under bot/, but bot/* only covers one level deep.

Cannot create a scoped token

• Tokens can only be created from the ChatBotKit dashboard. Navigate to chatbotkit.com/tokens to create and manage your tokens.

Next Steps

• Learn more about the ChatBotKit API in the API documentation
• Explore bot session creation for building chat applications
• Read about building an AI chatbot with Next.js and the ChatBotKit SDK