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 Developer > Data > API Integration 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
• <<thread_id>> - ID of the current conversation (empty outside a conversation)
• <<first_user_message>> - The customer’s first message in the conversation
• <<user_messages>> - All the customer’s messages in the conversation so far, oldest first, separated by a blank line

JWT claims are available through <<jwt.claimName>>, including nested paths such as <<jwt.user.id>>. A placeholder occupying the entire JSON value preserves its original type: "<<jwt.userId>>" becomes a JSON number when the JWT claim is numeric.

If the external API requires a string, use "<<jwt.userId|string>>". For example, {"organizationId": "<<jwt.userId|string>>"} sends {"organizationId": "12345"} when userId is the number 12345 in the JWT.

Using the Conversation

The conversation placeholders let an external service answer about the conversation itself, not only about the user. For example, a classifier can tell the agent whether the customer’s request should go straight to a ticket:

{
  "conversation_id": "<<thread_id>>",
  "message": "<<first_user_message>>"
}

Map the fields of the response (for example covered and category) with Include in Conversation enabled, then tell the agent in its instructions what to do with them.

A source that uses a conversation placeholder caches one response per conversation, so a response is never reused in another conversation:

• With <<first_user_message>>, the service is called once per conversation and the cached response is reused on every later message while the cache is valid.
• With <<user_messages>>, the service is called again after each new customer message. Use it when the first message is often only a greeting.

The source is called before each agent answer, so the service’s response time adds to the agent’s response time when the cache is empty. Clearing a user’s cache does not clear these per-conversation responses; they expire with the cache TTL.

Answer with a workflow

Instead of calling an external API, a source can be answered by a workflow that runs inside AGO, for example to call your classifier, tag the conversation with its answer (kb_covered or kb_not_covered) and return the answer to the agent. No URL, secret or request template is needed.

1. Create a workflow, set Execution to Wait for the result in its Settings, and publish it. Any trigger works.
2. Edit the source, set Answered by to AGO workflow and choose the workflow. Workflows that run in the background or are not published yet are shown but cannot be selected.

The workflow receives these inputs:

Input	Value
thread_id	ID of the current conversation, empty outside a conversation
first_user_message	The customer’s first message
user_messages	All the customer’s messages so far, oldest first
user_id	Internal ID of the user
email	Email address of the user

Its result becomes the source’s response: Response Data Path, Excluded Response Paths, context mappings and permission rules apply to it as to an API response. The workflow runs with its creator’s permissions and must finish within 20 seconds.

While the cache is valid, the workflow runs once per conversation; disable the cache to run it before every answer. If it fails, the agent answers without this context and the error is shown in the workflow’s Executions; the next message runs it again. The test panel has no conversation, so thread_id is empty and a Tag conversation block tags nothing. A workflow used by a source cannot be deleted; choose another workflow or switch the source back to its API first. The source keeps its API settings while a workflow answers, so switching back restores them.

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.

HMAC-SHA256 Authentication

Enable Sign requests with HMAC-SHA256 and enter the shared HMAC secret. The secret is stored encrypted and is never returned by the configuration API. When editing a source, leave the secret empty to keep it, or enter a new value to replace it. You do not need to re-enter the secret when changing other settings. Disabling and re-enabling HMAC signing also retains the stored secret.

For every outgoing request, AGO generates:

• X-Timestamp: the current Unix timestamp in seconds.
• X-Signature: the lowercase hexadecimal HMAC-SHA256 of timestamp.body, using your secret as a UTF-8 key and the exact request body bytes. For GET requests, the body is empty.

These two headers are generated automatically and override any manually configured values. Add other required headers, such as X-Partner-Id, in Request Headers.

For a partner context endpoint, choose POST and configure these headers:

{
  "Content-Type": "application/json",
  "X-Partner-Id": "your-partner-id"
}

Use this Request Body Template:

{
  "organizationId": "12345",
  "requesterEmail": "<<email>>"
}

If the organization comes from the authenticated user’s JWT, replace 12345 with <<jwt.organizationId>> (or the matching claim path).

Link the source to your agent in the agent settings so its response can enrich conversation context. HMAC uses the existing API data source loading and caching behavior: a cached response does not trigger a new HTTP request. Disable caching if you need fresh data on every context load. Use the source’s test panel to verify your configuration.

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 AI Studio > Permissions > API-based permissions
2. Click Add Rule
3. Select the API data source and 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	Equality with numeric or string conversion when needed	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 has a non-null value	subscription exists
not_exists	Field is absent or null	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.

Context Formatting

Included fields appear as a list of labels and values. For example:

- Subscription Plan: premium
- Available Credits: 100

Use each mapping’s Label to choose the displayed name. The Prompt Template field does not currently change this formatting.

Testing

Before deploying, test your configuration with real user data.

1. Navigate to Developer > Data > API Integration > Test API Data
2. Select the API data source
3. Enter an existing user’s email in User Email, or leave it empty to test with your own user
4. For a source that uses a conversation placeholder, type a sample message in Customer message. It is used as the first message and as the whole conversation
5. Click Run Test and review the API response, matched rules, and granted permissions

Selecting Sources for Permissions and Conversations

To choose the source used to resolve user permissions, navigate to AI Studio > Permissions > JWT-based permissions and select API to base the permission on. Create the corresponding rules in API-based permissions.

For conversation context, link the relevant API data sources directly to each agent in its settings. Conversation context uses those linked sources; the permission source is not a fallback for agents without linked sources.

Troubleshooting

In a conversation’s Full Thread Debug, expand an assistant message and look for API source in its metrics waterfall. Each context fetch shows its duration, source name, outcome, and HTTP status when available. Failed calls appear in red; expand them for the error cause, such as a timeout, missing authentication, or a missing response data path. The API Sources tab also lists these calls by message, including failures with no fetched data.

When debug data storage is enabled, expanding a call also shows the outgoing method, URL, query parameters, headers, and JSON body after placeholder substitution. Email addresses are retained for debugging. Credentials and other sensitive fields, including phone numbers and names, are masked before these request details are saved. Authentication headers, cookies, and HMAC signatures are masked. Response bodies are not included in the call trace.

Cache hits and simulation overrides are identified separately because no HTTP request is sent. Durations cover the full context fetch, including preparation and response processing. These details are available for newly recorded calls; they cannot be recovered for older messages.

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 applies to the source selected in API to base the permission on. Run a test to inspect the returned API data, matched rules, and granted permissions. If a rule does not match, compare its conditions with the returned data. 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.