API Data Sources

Connect external APIs to fetch user-specific data and configure permission rules based on that data

API Data Sources allow you to connect external APIs (such as CRM systems, subscription platforms, or user databases) to fetch user-specific data. You can use this data to dynamically grant permissions or enrich AI conversations with business context.

Overview

With API Data Sources, you can:

• Connect External APIs: Configure secure connections to fetch user data from external systems
• Define Permission Rules: Automatically grant permissions based on API response data
• Enrich Conversations: Include relevant user context in AI agent conversations
• Test Configurations: Validate API connections and permission rules for specific users

Creating an API Data Source

Navigate to Settings > API Data Sources to create a new connection.

Basic Settings:

Field	Description	Example
Name	Unique name for this data source	CRM User Data
Description	Purpose of this API connection	Fetches subscription data
API URL	Endpoint URL with optional placeholders	https://api.example.com/users/<<email>>
HTTP Method	Request method (GET or POST)	GET
Timeout	Request timeout in seconds	10

URL Placeholders

Use the following placeholders in your API URL, headers, or request body:

• <<email>> - User’s email address
• <<user_id>> - Internal user ID
• <<username>> - Username
• <<clerk_id>> - Clerk authentication ID
• <<api_key>> - Your configured API key

Authentication

API Key: Enter your API key in the dedicated field. It is encrypted and stored securely. Reference it in headers using the <<api_key>> placeholder.

Forward User Auth: Enable this option to pass the user’s authentication token to the external API. Useful when the external API needs to verify the user’s identity directly.

JWT Query Parameters

Map JWT claim values to URL query parameters for user-specific API calls. This allows you to pass information from the user’s authentication token directly as query parameters to the external API.

Configuration:

Each mapping consists of:

• Parameter Name: The query parameter name to add to the URL
• JWT Claim Path: Dot-notation path to the value in the JWT claims (e.g., user.department)

Example:

With a mapping of department → user.department and a JWT containing:

{
  "user": {
    "department": "Engineering"
  }
}

The API URL https://api.example.com/data becomes https://api.example.com/data?department=Engineering.

If a JWT claim is missing or empty, that parameter is silently skipped. This feature requires JWT-authenticated widget users.

Response Configuration

Response Data Path: If your API wraps data in nested objects, specify the path to extract the relevant data using dot notation.

For example, if your API returns:

{
  "status": "success",
  "data": {
    "user": { "plan": "premium" }
  }
}

Set the response data path to data.user to extract just the user object.

Caching

Setting	Description	Default
Cache Enabled	Cache API responses to reduce external calls	Enabled
Cache TTL	How long to cache responses (in seconds)	600 (10 minutes)

Permission Rules

Permission rules define conditions that, when matched against API data, automatically grant specific permissions to users.

Creating a Permission Rule

1. Navigate to your API Data Source
2. Click Add Permission Rule
3. Configure the rule name, priority, conditions, and permissions to grant

Conditions

Each condition has a field, operator, and value. All conditions in a rule must match (AND logic).

Operator	Description	Example
equals	Exact match	plan equals "premium"
not_equals	Does not match	status not_equals "suspended"
contains	Text or list contains value	features contains "api_access"
in	Value is in a list	tier in ["gold", "platinum"]
greater_than	Numeric comparison	credits greater_than 50
less_than	Numeric comparison	usage less_than 100
exists	Field is present	subscription exists
not_exists	Field is absent	suspension_date not_exists
starts_with	Text starts with value	email starts_with "admin"
ends_with	Text ends with value	domain ends_with ".enterprise"
regex	Regular expression match	phone regex "^\+1"

Example

Grant premium permissions to users with an active premium subscription:

[
  { "field": "subscription.plan", "operator": "equals", "value": "premium" },
  { "field": "subscription.status", "operator": "equals", "value": "active" }
]

If you need OR logic, create separate rules with different priorities.

Context Mappings

Context mappings extract fields from API responses and include them in AI conversations, giving agents relevant business context about users.

Field Mapping Configuration

Component	Description	Example
Source Field	JSON path in the API response	subscription.plan
Target Field	Key name in the business context	user_plan
Label	Human-readable label	Subscription Plan

Enable Include in Conversation to share the mapped data with AI agents.

Prompt Template

Optionally customize how context data appears in AI conversations:

This user is on the {plan} plan with {available_credits} credits remaining.

Without a custom template, the system uses default formatting.

Testing

Before deploying, test your configuration with real user data.

1. Navigate to your API Data Source
2. Click Test API Connection
3. Enter a test user identifier (email, user ID, etc.)
4. Review the API response, matched rules, and granted permissions

Global Settings

Navigate to Settings > API Data Sources > Configuration to manage:

Setting	Description
Enable Permission Rules	Master switch to enable/disable all permission rules
Default API Data Source	Primary data source when multiple are configured

Troubleshooting

API Connection Fails: Verify the API URL, authentication credentials, and placeholder formatting. Check timeout settings if the external API is slow.

Permission Rules Not Working: Verify the rule is active and that permission rules are globally enabled. Test with sample data to see which conditions fail. Clear the cache and retry.

Context Data Not Appearing: Verify the context mapping is active and that “Include in Conversation” is enabled. Check that field mappings match the API response structure.

Slow Performance: Enable caching, increase cache TTL, or reduce the API timeout setting.