Authentication

AgenticWork supports multiple authentication methods for flexibility across different use cases.

Authentication Methods

1. API Key (Recommended for Server-Side)

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

curl -H "X-API-Key: aw_live_xxxxxxxxxxxx" \
  https://chat.agenticwork.io/api/chat/sessions

API Key Prefixes:

Prefix	Environment
aw_live_	Production
aw_test_	Testing/Sandbox

2. Bearer Token (OAuth/JWT)

For user-authenticated requests:

curl -H "Authorization: Bearer eyJhbG..." \
  https://chat.agenticwork.io/api/chat/sessions

3. Azure AD SSO

For enterprise SSO integration:

1. User is redirected to Azure AD login

2. Azure AD returns authorization code

3. AgenticWork exchanges code for tokens

4. Session is established with user identity

API Key Management

Creating API Keys

Via Admin Portal:

1. Navigate to Settings > API Keys

2. Click "Create New Key"

3. Set permissions and rate limits

4. Copy the key (shown only once)

Via API:

curl -X POST https://chat.agenticwork.io/api/admin/api-keys \
  -H "Authorization: Bearer admin-token" \
  -d '{
    "name": "Production Backend",
    "permissions": ["chat", "mcp"],
    "rateLimitTier": "pro"
  }'

Rate Limit Tiers

Tier	Requests/min	Daily Limit
free	10	100
pro	100	10,000
enterprise	1000	Unlimited
custom	Configurable	Configurable

Revoking Keys

curl -X DELETE https://chat.agenticwork.io/api/admin/api-keys/key-id \
  -H "Authorization: Bearer admin-token"

Permission Scopes

API keys can be scoped to specific permissions:

Scope	Access
chat	Chat sessions and messages
mcp	MCP tool execution
admin	Admin portal functions
flowise	Flowise workflows
code	AgentiCode execution

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

{
  "error": "forbidden",
  "message": "API key does not have required permissions"
}

429 Too Many Requests

{
  "error": "rate_limited",
  "message": "Rate limit exceeded",
  "retryAfter": 60
}

Security Best Practices

1. Never expose keys in client-side code - Use server-side proxies

2. Rotate keys regularly - Create new keys and deprecate old ones

3. Use minimal permissions - Only grant necessary scopes

4. Monitor usage - Watch for unusual patterns in the Admin Portal

5. Use environment variables - Never commit keys to version control