API Authentication

Secure authentication for the Agoralia Public API using API keys with scoped permissions and tenant isolation.

Overview

The Agoralia Public API uses API keys for authentication. Each API key:

Has scopes that define what operations it can perform
Is scoped to a specific workspace/tenant (tenant isolation)
Can have an optional expiration date
Tracks usage statistics (last used, request count)
Is stored securely (keys are never stored in plain text)

Prerequisites

Admin or Owner role in your Agoralia workspace
Access to Settings → Security and API → API Keys

1. Create an API Key

Via Web Interface

Sign in to your Agoralia workspace
Navigate to Settings → Security and API → API Keys
Click Create API Key
Configure:
- Name: Descriptive name (e.g., "Production Integration", "Zapier Webhook", "Mobile App")
- Scopes: Select one or more required permissions (see Scopes below)
- Expiration (optional): Set expiration date for temporary keys
Click Create
Copy the key immediately - it will only be shown once!

The API key format is: ago_ followed by 32 random alphanumeric characters (e.g., ago_ETWIQRPbBXBrMxwcyxqUFLlYGErtFOaa)

API Key Format

Prefix: ago_
Length: 35 characters total (ago_ + 32 random chars)
Characters: Letters (a-z, A-Z) and digits (0-9)
Example: ago_ETWIQRPbBXBrMxwcyxqUFLlYGErtFOaa

2. Use the API Key

Include the API key in the X-API-Key header for all requests:

curl -X GET "https://api.agoralia.app/api/v1/me" \
  -H "X-API-Key: ago_ETWIQRPbBXBrMxwcyxqUFLlYGErtFOaa"

Base URL: https://api.agoralia.app/api/v1

Example Request

curl -X GET "https://api.agoralia.app/api/v1/agents" \
  -H "X-API-Key: ago_ETWIQRPbBXBrMxwcyxqUFLlYGErtFOaa" \
  -H "Content-Type: application/json"

Example Response

{
  "tenant_id": 1234,
  "workspace_name": "My Workspace",
  "plan": "pro",
  "rate_limits": {
    "rpm": 120,
    "rpd": 20000
  },
  "api_key_scopes": ["me:read", "agents:read", "agents:write"]
}

The api_key_scopes field in the /me endpoint response shows which scopes your API key has, so you can verify what operations it can perform.

3. Scopes

API keys support granular scopes that control access to specific operations. Scopes follow the format resource:action.

Available Scopes

Scope	Description
`me:read`	Read your tenant information
`agents:read`	List and read agents
`agents:write`	Create and update agents
`campaigns:read`	List and read campaigns
`campaigns:write`	Create and update campaigns
`campaigns:start`	Start campaigns
`leads:write`	Create and update leads
`calls:read`	Read call records
`results:read`	Read campaign results

Wildcard Scopes

You can use wildcard scopes to grant all permissions for a resource:

campaigns:* - Grants campaigns:read, campaigns:write, and campaigns:start
agents:* - Grants agents:read and agents:write

Example: A webhook integration might only need calls:read scope, while a full integration might need campaigns:* and agents:*.

Scope Validation

When you make a request, the API checks:

If the required scope is in your API key's scope list (exact match)
If a wildcard scope matches (e.g., campaigns:* matches campaigns:write)

If neither condition is met, you'll receive a 403 Forbidden error.

4. Manage API Keys

View API Keys

Go to Settings → Security and API → API Keys to see:

Key name and prefix (first 8 characters)
Scopes granted
Creation date
Last used date
Request count
Expiration date (if set)
Status (active/revoked/expired)

Revoke a Key

If a key is compromised or no longer needed:

Go to Settings → Security and API → API Keys
Find the key in the list
Click Revoke
Confirm the action

The key will immediately stop working and disappear from the active list. Revoked keys cannot be reactivated.

Expiration

API keys can have an optional expiration date. When a key expires:

It automatically stops working
You'll receive 401 Unauthorized errors
You need to create a new key

Expired keys are shown separately in the API keys list.

5. Security Best Practices

✅ Do

Never commit API keys to version control or public repositories
Use environment variables for keys in production code
Rotate keys regularly (every 90 days recommended)
Use minimal scopes - only grant what's needed for the integration
Set expiration dates for temporary integrations
Monitor key usage in Settings → Security and API → API Keys
Revoke unused keys immediately

❌ Don't

Share API keys between team members (create separate keys)
Use the same key for multiple environments (dev/staging/prod)
Include keys in client-side code or mobile apps (use a backend proxy)
Log API keys in application logs
Send API keys via email or chat

Key Storage Examples

Environment Variables (recommended):

export AGORALIA_API_KEY="ago_ETWIQRPbBXBrMxwcyxqUFLlYGErtFOaa"

Python:

import os
api_key = os.getenv("AGORALIA_API_KEY")

Node.js:

const apiKey = process.env.AGORALIA_API_KEY;

6. How Authentication Works

Request Flow

Client sends request with X-API-Key header
Server validates key:
- Checks key format (must start with ago_ and be 35 chars)
- Verifies key is active, not revoked, and not expired
Server checks scopes:
- Extracts required scope from endpoint
- Verifies API key has required scope (exact or wildcard match)
Server processes request if authentication succeeds
Server updates usage stats (last_used_at, request_count)

Key Storage Security

Keys are never stored in plain text in the database
Only the key prefix (first 8 chars) is stored for display
The full key is only shown once when created

7. Troubleshooting

401 Unauthorized

Possible causes:

API key is incorrect or mistyped
API key has been revoked
API key has expired
API key format is invalid

Solutions:

Verify the API key is correct (check for typos)
Check if the key is revoked in Settings → Security and API → API Keys
Verify expiration date hasn't passed
Ensure key starts with ago_ and is 35 characters long
Create a new API key if needed

403 Forbidden

Possible causes:

API key doesn't have the required scope for the endpoint
Scope was removed after key creation

Solutions:

Check the required scope in the endpoint documentation
Verify your API key's scopes in Settings → Security and API → API Keys
Create a new API key with the correct scopes
Check the /me endpoint response to see api_key_scopes

Example error:

{
  "detail": "Insufficient permissions. Required scope: campaigns:write"
}

Key Not Found

If you've lost your API key:

You cannot recover it (keys are securely stored and never shown again)
You must create a new API key
Revoke the old key if you suspect it was compromised

8. Usage Tracking

Each API key tracks:

Last used date: When the key was last used
Last used IP: IP address of the last request
Last used user agent: User agent string from last request
Request count: Total number of requests made with this key

View this information in Settings → Security and API → API Keys.

Next Steps

Endpoints Reference - Learn about available API endpoints
Idempotency - Ensure safe retries
Rate Limits - Understand API quotas
Error Handling - Handle API errors gracefully

API Authentication

Overview​

Prerequisites​

1. Create an API Key​

Via Web Interface​

API Key Format​

2. Use the API Key​

Example Request​

Example Response​

3. Scopes​

Available Scopes​

Wildcard Scopes​

Scope Validation​

4. Manage API Keys​

View API Keys​

Revoke a Key​

Expiration​

5. Security Best Practices​

✅ Do​

❌ Don't​

Key Storage Examples​

6. How Authentication Works​

Request Flow​

Key Storage Security​

7. Troubleshooting​

401 Unauthorized​

403 Forbidden​

Key Not Found​

8. Usage Tracking​

Next Steps​