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.

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

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 →

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

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 →

Configuration

Configure the API key through backend settings:

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

Example Request

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

Control which agents users can access

Access Control Rules

Define rules for user access

Access Control Examples

Practical examples of access control configuration

User Impersonation

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

Authentication for embedded widget integrations

API Key Authentication

Server-to-server API key authentication

Agent Permissions

Control which agents users can access

Access Control Rules

Define rules for user access

Access Control Examples

Practical examples of access control configuration