Skip to main content

​
Overview

The AgentHuman Client API (/v1/*) supports two authentication methods:
  1. JWT Authentication (Cookie-based) - Used for agent management endpoints
  2. API Key Authentication - Used for session and message endpoints
Most endpoints accept both authentication methods, but some are specific to one type.

​
Getting Your API Key

​
Option 1: Web Dashboard

  1. Sign in to your account at app.agenthuman.com
  2. Navigate to Settings → API Keys
  3. Click “Create New API Key”
  4. Give your key a descriptive name
  5. Copy and securely store your key

​
Option 2: Programmatic Access

You can also manage API keys programmatically after authentication:
  • Create API Key - Generate new API keys
  • List API Keys - View existing keys
  • See the Authentication endpoints for OTP and JWT-based authentication
API keys are shown only once when created. Store them securely and never expose them in client-side code or public repositories.

​
Authentication Methods

​
1. JWT Authentication

JWT authentication is used for agent management endpoints. Include the JWT token in the Authorization header: 
GET /v1/agents
Authorization: Bearer <jwt_token>
JWT-authenticated endpoints:
  • Agent CRUD operations (/v1/agents)
  • User-specific resources for avatars, voices, and roles

​
2. API Key Authentication

API key authentication is used for session and message endpoints. Include your API key in the x-api-key header: 
GET /v1/sessions
x-api-key: ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
API Key-authenticated endpoints:
  • Session management (/v1/sessions)
  • Message endpoints (/v1/sessions/{id}/messages)
  • Public resource lists (avatars, voices, roles)

​
API Key Format

AgentHuman API keys follow a consistent format: 
ah_[environment]_[random_string]
  • ah_ - Prefix identifying an AgentHuman key
  • environment - Either live for production or test for testing
  • random_string - A unique 32-character string
Examples:
  • Production: ah_live_1234567890abcdefghijklmnopqrstuv
  • Test: ah_test_1234567890abcdefghijklmnopqrstuv

​
Environment Variables

For security, store API keys in environment variables: 
AGENTHUMAN_API_KEY=ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Security Best Practices

​
Do’s ✅

  • Store API keys in environment variables or secure key management systems
  • Use different keys for different environments (development, staging, production)
  • Rotate keys regularly
  • Monitor key usage for unusual activity
  • Revoke compromised keys immediately

​
Don’ts ❌

  • Hard-code API keys in your source code
  • Commit API keys to version control
  • Share API keys via email or chat
  • Use API keys in client-side JavaScript
  • Log or display API keys in error messages

​
Key Management

​
Rotating Keys

Regularly rotate your API keys for enhanced security:
  1. Create a new API key
  2. Update your application to use the new key
  3. Test thoroughly
  4. Delete the old key

​
Revoking Keys

If a key is compromised:
  1. Sign in to your account immediately
  2. Navigate to Settings → API Keys
  3. Find the compromised key
  4. Click “Delete” to revoke it instantly
  5. Create a new key if needed

​
Error Responses

​
Invalid API Key

{
  "success": false,
  "error": "Invalid API key"
}
HTTP Status: 401 Unauthorized

​
Missing API Key

{
  "success": false,
  "error": "API key required"
}
HTTP Status: 401 Unauthorized

​
Expired or Revoked Key

{
  "success": false,
  "error": "API key has been revoked"
}
HTTP Status: 401 Unauthorized

​
Testing Authentication

​
Using the API Playground

The easiest way to test your API key is using the built-in API Playground:
  1. Navigate to any API endpoint documentation page
  2. Look for the “API Playground” section
  3. Enter your API key in the x-api-key field
  4. Fill in any required parameters
  5. Click “Send Request” to test the endpoint
The API Playground will automatically include your API key in all requests once entered.

​
Manual Testing

You can also test your API key with these simple requests: 
curl -X GET https://jwhite.tail8bf327.ts.net/api/v1/sessions \
  -H "x-api-key: your_api_key_here"

​
Need Help?

If you’re having authentication issues:
  1. Verify your API key is correct and hasn’t been revoked
  2. Check that you’re using the correct header name (x-api-key)
  3. Ensure you’re using HTTPS for all requests
  4. Contact support at [email protected] if issues persist