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

# Security Overview

> Multi-layered authentication system for various deployment scenarios

AGO provides a flexible, multi-layered authentication system that supports various authentication methods to accommodate different use cases and deployment scenarios. This document provides an overview of all available authentication mechanisms and how they work together.

## Overview

The AGO platform implements a **multi-authentication system** that tries different authentication methods in sequence until one succeeds. This approach ensures compatibility with various client types while maintaining security standards.

### How Multi-Authentication Works

When a request is received, AGO's authentication system processes it in the following order:

1. **Clerk JWT Authentication**: Checks for `Authorization: Bearer <token>` header
2. **Reverse Proxy Authentication** (deployment-specific): Checks for headers set by an authenticating reverse proxy, if configured
3. **Widget Authentication**: Checks for the `X-User-Anon-Id` header
4. **API Key Authentication**: Checks for `X-API-Key` header

If any authentication method succeeds, the request is authorized and proceeds. If all methods fail, the request is rejected as unauthorized.

> [!NOTE]
>
> Reverse proxy authentication is only active in deployments that use an authenticating reverse proxy. Most deployments use Clerk JWT, Widget, or API Key authentication.

## Available Authentication Methods

AGO supports the following authentication mechanisms:

**Clerk JWT**

**Use Case**: Primary authentication for web applications and authenticated users

**How It Works**: Uses JSON Web Tokens (JWT) issued by Clerk for user authentication. The JWT is sent via the `Authorization: Bearer <token>` header.

**Best For**:

* Web applications
* Mobile applications
* Authenticated user sessions
* Multi-tenant environments

#### Configuration

Clerk authentication requires your Clerk instance's JWKS URL to be configured in the AGO backend settings. This URL points to Clerk's public keys used to verify JWT signatures.

#### How It Works

1. **Request Received**: AGO receives a request with `Authorization: Bearer <jwt-token>` header
2. **JWKS Retrieval**: The system fetches the JSON Web Key Set (JWKS) from Clerk (cached for 1 hour)
3. **Token Verification**: The JWT is verified using RS256 algorithm and validated against Clerk's public keys
4. **User Creation/Update**: User is created or updated based on JWT claims:
   * Email from `email` claim
   * First name from `firstName` claim
   * Last name from `lastName` claim
   * Clerk user ID from `sub` claim
5. **Organization Linking**: User is automatically linked to their organization based on email domain
6. **Access Control**: System verifies the user has access to the current tenant
7. **Request Processing**: The request proceeds with the authenticated user

#### Example Request

```bash theme={null}
curl -X GET https://api.example.com/api/endpoint \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

#### Security Considerations

* JWT tokens are verified using RS256 asymmetric encryption
* JWKS is cached for performance (1 hour TTL)
* Tokens are validated for audience: `https://api.clerk.com`
* User information is automatically synchronized on each request
* Access control is enforced at the tenant level

#### Troubleshooting

**JWT verification fails**

* Verify token hasn't expired
* Check that JWKS URL is accessible
* Ensure token signature is valid
* Confirm audience claim matches configuration

**User not created or updated**

* Check user permissions in the admin interface
* Contact your administrator if user creation errors persist
* Verify JWT claims include required fields (email, sub)
* Ensure Clerk user ID format is valid

**Widget**

**Use Case**: Third-party website integrations

**How It Works**: Uses a combination of widget IDs, allowed-domain validation, and optional JWT tokens to authenticate users accessing AGO through embedded widgets.

**Best For**:

* Website embeds
* Public-facing widgets
* Third-party integrations
* Anonymous and authenticated widget users

[Learn more about Widget Authentication →](https://ago.mintlify.site/security/widget-authentication.md)

#### Configuration

Widget authentication is configured through backend settings:

* `widget_allowed_domains`: List of allowed domains (e.g., `["https://example.com", "https://app.example.com"]`)
* `widget_jwt_jwks_url`: (Optional) JWKS URL for JWT verification
* `widget_default_permission`: Default permission for anonymous widget users
* `widget_logged_in_default_permission`: Default permission for authenticated widget users

#### Example Request

```javascript theme={null}
fetch('https://api.example.com/api/endpoint', {
    headers: {
        'X-User-Anon-Id': 'unique-widget-instance-id',
        'Origin': 'https://example.com',
        'Authorization': 'Bearer <jwt-token>'  // Optional for authenticated users
    }
})
```

**API Key**

**Use Case**: Server-to-server integrations and automated workflows

**How It Works**: Uses a static API key sent via the `X-API-Key` header to authenticate system-level requests.

**Best For**:

* Server-to-server communication
* Automated workflows
* Integration with external systems
* Background jobs and scheduled tasks

[Learn more about API Key Authentication →](https://ago.mintlify.site/security/api-key-authentication.md)

#### Configuration

Configure the API key through backend settings:

Set the **API Key** field with a strong, random key (32+ characters recommended).

#### Example Request

```bash theme={null}
curl -X POST https://api.example.com/api/endpoint \
  -H "X-API-Key: your-secure-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'
```

## Security Best Practices

### General Security Guidelines

1. **HTTPS Only**: All authentication methods must be used over HTTPS in production
2. **Key Rotation**: Regularly rotate API keys and secrets (recommended: every 90 days)
3. **Environment Separation**: Use different credentials for development, staging, and production
4. **Least Privilege**: Grant only necessary permissions to users and systems
5. **Audit Logging**: Monitor authentication attempts and access patterns
6. **Rate Limiting**: Implement rate limiting to prevent brute force attacks

### Authentication-Specific Guidelines

* **JWT Tokens**: Keep tokens short-lived and implement proper refresh token flows
* **API Keys**: Store securely in environment variables or secret management systems
* **Widget Keys**: Configure allowed domains to prevent unauthorized usage

### What NOT to Do

* ❌ Don't commit API keys or secrets to version control
* ❌ Don't share credentials across environments
* ❌ Don't use simple or predictable keys
* ❌ Don't send credentials over unencrypted connections
* ❌ Don't log sensitive authentication data
* ❌ Don't share API keys in public documentation or examples

## Access Control & Permissions

Beyond authentication, AGO implements fine-grained access control:

> **[Agent Permissions](https://ago.mintlify.site/users/agent-permissions.md)**
>
> Control which agents users can access

> **[Access Control Rules](https://ago.mintlify.site/users/access-control-rules.md)**
>
> Define rules for user access

> **[Access Control Examples](https://ago.mintlify.site/users/access-control-examples.md)**
>
> Practical examples of access control configuration

> **[User Impersonation](https://ago.mintlify.site/users/impersonate.md)**
>
> Temporarily assume another user's identity for support purposes

## Configuration

All authentication methods are configured through backend settings:

* **API Key**: For server-to-server authentication
* **Allowed Domains**: For widget domain validation
* **JWT Configuration**: For Clerk and widget JWT authentication
* **Default Permissions**: For widget users (authenticated and anonymous)

## Troubleshooting

### Common Issues

> **Authentication fails for all methods**
>
> * Check that the request includes proper authentication headers
> * Verify credentials match configuration
> * Review server logs for specific error messages
> * Ensure the authentication method is properly configured

> **CORS errors with widget authentication**
>
> * Add the widget domain to `widget_allowed_domains`
> * Ensure HTTPS is used on both ends
> * Check browser console for specific CORS errors

> **JWT verification fails**
>
> * Verify token hasn't expired
> * Check that public keys are properly configured
> * Ensure token signature is valid
> * Confirm JWKS URL is accessible

> **API key rejected**
>
> * Confirm API key matches the configured value
> * Check that the `X-API-Key` header is being sent
> * Verify no whitespace or formatting issues in the key
> * Ensure the header name is exactly `X-API-Key` (case-sensitive)

> **Widget authentication fails**
>
> * Verify the Origin header is in the allowed domains list
> * Ensure the X-User-Anon-Id header is present
> * Review widget configuration in admin panel

> **Authentication order issues**
>
> * Remember that Clerk auth is tried first, so if a Bearer token is present, it will be used
> * Widget auth is only tried if Clerk auth fails
> * API key auth is attempted last

### Getting Help

For additional support:

* Check the specific authentication method documentation
* Review server logs for detailed error messages
* Verify configuration in AGO admin panel
* Contact your system administrator or AGO support team

## Related Documentation

> **[Widget Authentication](https://ago.mintlify.site/security/widget-authentication.md)**
>
> Authentication for embedded widget integrations

> **[API Key Authentication](https://ago.mintlify.site/security/api-key-authentication.md)**
>
> Server-to-server API key authentication

> **[Agent Permissions](https://ago.mintlify.site/users/agent-permissions.md)**
>
> Control which agents users can access

> **[Access Control Rules](https://ago.mintlify.site/users/access-control-rules.md)**
>
> Define rules for user access

> **[Access Control Examples](https://ago.mintlify.site/users/access-control-examples.md)**
>
> Practical examples of access control configuration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.