API Authentication¶

All Customer API requests require authentication via API key.

API Key Format¶

cust_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: cust_ (always)
• Body: 32+ URL-safe characters
• Example: cust_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using API Keys¶

Include your API key in the X-API-Key header:

GET /api/v1/agents HTTP/1.1
Host: agents.ag2trust.com
X-API-Key: cust_your_api_key_here

Examples¶

curl https://agents.ag2trust.com/api/v1/agents \
  -H "X-API-Key: cust_your_api_key_here"

import requests

response = requests.get(
    "https://agents.ag2trust.com/api/v1/agents",
    headers={"X-API-Key": "cust_your_api_key_here"}
)
print(response.json())

import httpx

async with httpx.AsyncClient() as client:
    response = await client.get(
        "https://agents.ag2trust.com/api/v1/agents",
        headers={"X-API-Key": "cust_your_api_key_here"}
    )
    print(response.json())

const response = await fetch(
  'https://agents.ag2trust.com/api/v1/agents',
  {
    headers: {
      'X-API-Key': 'cust_your_api_key_here'
    }
  }
);
const data = await response.json();

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://agents.ag2trust.com',
  headers: {
    'X-API-Key': 'cust_your_api_key_here'
  }
});

const response = await client.get('/api/v1/agents');

Generating API Keys¶

1. Log in to app.ag2trust.com
2. Navigate to Settings > API Keys
3. Click Generate API Key
4. Enter a name (e.g., "Production", "Development")
5. Click Generate
6. Copy the key immediately - it won't be shown again

Managing API Keys¶

Multiple Keys¶

Create separate keys for different environments:

Revoking Keys¶

1. Go to Settings > API Keys
2. Find the key to revoke
3. Click Revoke
4. Confirm the action

Security Best Practices¶

Do¶

• Store keys in environment variables
• Use different keys per environment
• Rotate keys periodically
• Monitor usage for anomalies
• Revoke unused keys

Don't¶

• Commit keys to version control
• Expose keys in client-side code
• Share keys via insecure channels
• Log keys in plain text
• Use production keys for testing

Environment Variables¶

# .env file (never commit this!)
AG2TRUST_API_KEY=cust_your_api_key_here

# In your code
import os
api_key = os.environ["AG2TRUST_API_KEY"]

Key Rotation¶

1. Generate a new API key
2. Update your applications to use the new key
3. Verify everything works
4. Revoke the old key

Authentication Errors¶

401 Unauthorized¶

{
  "error": "Invalid or missing API key",
  "error_code": "INVALID_API_KEY"
}

Causes:

• Missing X-API-Key header
• Invalid key format
• Key doesn't exist
• Key has been revoked

Solutions:

1. Verify the header name is exactly X-API-Key
2. Check for copy/paste errors (leading/trailing spaces)
3. Confirm the key exists in Dashboard
4. Generate a new key if necessary

403 Forbidden¶

{
  "error": "Agent not found or not owned by customer",
  "error_code": "AGENT_NOT_FOUND"
}

Causes:

• Trying to access an agent that doesn't exist
• Agent belongs to a different organization

Solutions:

1. Verify the agent ID is correct
2. Confirm the agent is in your organization
3. Use GET /api/v1/agents to list your agents

API Key Caching¶

For performance, AG2Trust caches API key validations:

This means:

• New keys work immediately
• Revoked keys may work for up to 5 minutes
• Plan key rotations accordingly

Rate Limits by Key¶

Each API key has its own rate limit quota:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700308800

Multiple keys from the same organization share the organization's overall quota.

Next Steps¶

• Send messages to agent pools
• Send messages to specific agents
• Set up webhooks