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

# Integration Architecture

> Understand AGO's two APIs, their authentication models, and how to choose the right one for your integration.

AGO exposes two distinct APIs designed for different integration scenarios. The **SDK API** powers end-user-facing experiences like chat widgets and mobile apps, while the **Public API v1** supports server-to-server automation, knowledge management, and admin operations. Understanding the difference between them is essential for choosing the right approach for your project.

## Choosing the Right API

| Use case                                    | API                 | Why                                                          |
| ------------------------------------------- | ------------------- | ------------------------------------------------------------ |
| Building a chat UI                          | SDK API             | Designed for real-time conversation from the browser         |
| Mobile app integration                      | SDK API             | Lightweight auth, supports anonymous and authenticated users |
| Server-to-server automation                 | Public API v1       | API key auth, scoped access, IP allowlists                   |
| Managing your knowledge base                | Public API v1       | Full CRUD on documents and sources                           |
| Connecting MCP clients (Claude, Cursor)     | Public API v1 (MCP) | Exposes agents and tools via JSON-RPC 2.0                    |
| Admin operations (agents, tools, templates) | Public API v1       | Scoped keys control exactly what each integration can access |

## SDK API

The SDK API at `/api/sdk/v1/` is the interface your end users interact with, whether through the embeddable widget, a custom chat UI, or a mobile app.

### How It Works

Every request to the SDK API must include an `X-User-Anon-Id` header that identifies the user or session. AGO validates the `Origin` header against your configured allowed domains, ensuring requests only come from authorized origins.

With these credentials, AGO identifies which workspace the request belongs to and applies the appropriate configuration, including which agents are available, what the pre-chat form looks like, and how conversations are routed.

The SDK API exposes endpoints for conversations, messages, tickets, configuration, pre-chat forms, and incident info banners --- everything needed to build a complete support experience.

### Authentication Modes

The SDK API supports three authentication modes, each suited to a different stage of the user journey.

**Anonymous access** is the simplest mode. You send only the widget ID. AGO creates an anonymous user identity for the session, and the user receives default permissions. This is ideal for public-facing chat where you do not require users to log in.

**JWT authentication** adds an `Authorization: Bearer {jwt}` header to requests. AGO verifies the token against a JWKS URL you configure in the admin interface, supporting RS256, RS384, RS512, and ES256 algorithms. Once verified, AGO extracts the user's email and name from the token claims and associates the conversation with that identity. The user receives logged-in permissions, and you can define additional permission rules based on JWT claims.

**Auth token forwarding** uses an `X-Auth-Token` header instead of a JWT. AGO resolves the user's identity by calling an external API you configure. This mode is useful when your authentication system does not issue JWTs, or when you need AGO to validate tokens against your own backend. The user receives logged-in permissions once resolved.

You can also pass optional headers like `X-Widget-Email` and `X-Widget-Permission` to provide additional context about the user.

### Permission Model

Permissions in the SDK API depend on the authentication mode. Anonymous users get a baseline set of permissions suitable for public interactions. JWT-authenticated users get elevated permissions, and you can further refine access using permission rules tied to JWT claims. Auth-token users receive the same elevated permissions once their identity is resolved.

This tiered model lets you progressively enable functionality as users authenticate, without requiring separate API integrations for each level.

## Public API v1

The Public API v1 at `/api/v1/` is designed for backend integrations, automation workflows, and administrative operations.

### How It Works

Every request to the Public API must include an `X-API-Key` header. API keys follow the format `ago_v1_sk_` followed by the key value, making them easy to identify in logs and configuration files.

Unlike the SDK API, the Public API does not represent an end user. It represents a system-level integration with explicit permissions defined by the key's scopes.

### API Key Scopes

Each API key is issued with a specific set of scopes that control which endpoints it can access. For example, a key with the `knowledge:read` scope can query documents and sources but cannot modify them. A key with `conversations:read` can retrieve conversation history but cannot create new conversations.

This scope-based model follows the principle of least privilege. You create keys with only the permissions your integration actually needs, reducing the blast radius if a key is compromised.

Available endpoint categories include documents, sources, conversations, tickets, analytics, agents, tools, prompt templates, UI resource templates, and MCP.

### IP Allowlists

For additional security, you can restrict each API key to a set of IP addresses or CIDR ranges. Requests from IPs outside the allowlist are rejected, even if the key is valid. This is particularly useful for server-to-server integrations where the source IPs are known and fixed.

### Security Features

API keys include several built-in protections:

* **Auto-lockout** --- After 10 consecutive authentication failures, the key is automatically locked to prevent brute-force attacks.
* **Key rotation** --- You can rotate keys with a configurable grace period, allowing the old key to continue working while you update your integrations.
* **Audit logging** --- Every API request is logged, giving you a complete audit trail of what each key accessed and when.

## Authentication Comparison

|                          | Anonymous (SDK)                   | JWT (SDK)                               | Auth Token (SDK)                  | API Key (Public API)            |
| ------------------------ | --------------------------------- | --------------------------------------- | --------------------------------- | ------------------------------- |
| **Headers**              | `X-User-Anon-Id`                  | Same + `Authorization: Bearer {jwt}`    | Same + `X-Auth-Token`             | `X-API-Key`                     |
| **User identity**        | Auto-generated anonymous identity | Extracted from JWT claims (email, name) | Resolved via external API         | No user identity (system-level) |
| **Permissions**          | Default permissions               | Logged-in permissions + JWT-based rules | Logged-in permissions             | Scope-based access control      |
| **Domain/IP validation** | Origin must match allowed domains | Origin must match allowed domains       | Origin must match allowed domains | Optional IP allowlist (CIDR)    |
| **Best for**             | Public chat widgets               | Apps with existing auth                 | Non-JWT auth systems              | Server-to-server, automation    |

## MCP

AGO exposes an MCP (Model Context Protocol) endpoint on the Public API v1 at `/api/mcp`, using JSON-RPC 2.0. This allows MCP-compatible clients like Claude and Cursor to connect directly to your AGO workspace, giving AI assistants access to your agents and tools.

MCP access is governed by the same API key authentication and scoping as the rest of the Public API. You create a key with the appropriate scopes and configure your MCP client to use it.

For setup instructions, see the [MCP Integration Guide](/tools/mcp).

## Forwarding Auth to Tools

When your agents call external APIs on behalf of users, those APIs often need to know which user is making the request. AGO supports this through auth token forwarding.

Here is how it works: when a user authenticates via the SDK API using the `X-Auth-Token` header, and an agent invokes a tool configured with auth forwarding enabled, AGO includes the original auth token as an `X-Auth-Token` header in the outgoing HTTP request to the external API. The external API can then use this token to identify the user and enforce its own authorization rules.

This pattern is useful when your agents need to access user-specific data in external systems --- for example, looking up a user's order history or account details. The external API receives the same token your frontend would send, so it can apply the same authentication and authorization logic it already uses.

Auth forwarding is configured per tool. Only tools with the forwarding setting enabled will pass the token along, giving you fine-grained control over which external calls include user identity.

## Related Documentation

* [API Integration](/guides/api-integration) --- How to set up and use the Public API
* [SDK Integration](/guides/sdk-integration) --- How to embed AGO in your application
* [Widget Authentication](/guides/widget-authentication) --- Configure JWT and auth token verification
* [API Key Authentication](/guides/api-key-authentication) --- Create and manage API keys
* [MCP Integration Guide](/tools/mcp) --- Connect MCP clients to AGO