> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
[
  { "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.