Skip to main content

Overview

The Answering Agent Partner API uses API keys for authentication. API keys are simple, secure tokens that identify your partner account and authorize access to manage customer organizations, users, and locations.
This documentation covers the Partner API for building integrations. If you’re looking to embed the Answering Agent dashboard in your application, see the Embed Guide after completing initial setup.

How Authentication Works

  1. Generate an API Key from your Answering Agent partner dashboard
  2. Include the key in the X-API-KEY header for every API request
  3. Access granted - The API key identifies your partner account and provides access to your customer organizations
That’s it! No complex signing, no HMAC calculations, no timestamps. Just a simple API key in the request header.

Obtaining Your API Key

1

Sign in to your partner dashboard

Log in to the Answering Agent dashboard with your partner account credentials.
2

Navigate to API Keys settings

Go to Settings → API Keys in the dashboard navigation.
3

Generate a new key

Click Generate New Key. The key is displayed once—copy it immediately.
4

Store securely

Save the key in your backend environment variables or secrets manager. Never expose it in client-side code.
API keys are shown only once when created. If you lose a key, you’ll need to generate a new one and update your integration.
API Keys

Using Your API Key

Include your API key in the X-API-KEY header for every request to the Partner API:
curl -X GET "https://answeringagent.com/api/v1/organizations" \
  -H "X-API-KEY: sk_live_AbCdEfGhIjKlMnOpQrSt" \
  -H "Content-Type: application/json"

Required Header

X-API-KEY
string
required
Your API key from the partner dashboard. All partner API endpoints require this header.

Response Codes

StatusMeaningTypical Cause
200/201SuccessRequest completed successfully
401UnauthorizedMissing or invalid X-API-KEY header
403ForbiddenAPI key valid but lacks permission for this resource
404Not FoundResource doesn’t exist or doesn’t belong to your partner account
422Validation ErrorRequest data is invalid or incomplete
500Server ErrorUnexpected error on our side - contact support

Understanding Token Types

Answering Agent uses different authentication methods for different purposes. As a partner integrator, you only need to worry about API Keys.
Token TypeYou Need This ForHow to Get It
API KeyManaging customer organizations via Partner APIDashboard → Settings → API Keys
Embed TokenEmbedding dashboards in your applicationAPI endpoint /api/v1/users/{external_id}/embed-token
You may see references to “Bearer tokens” or login endpoints in our API. These are for internal use by the Answering Agent dashboard and are not needed for partner integrations.

Example Integration

Here’s a complete example of authenticating and creating your first customer organization:
# Store your API key securely
API_KEY="sk_live_AbCdEfGhIjKlMnOpQrSt"
BASE_URL="https://answeringagent.com/api/v1"

# Create a customer organization with owner
curl -X POST "${BASE_URL}/organizations" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "description": "A technology company",
    "owner": {
      "external_id": "user_123",
      "email": "[email protected]",
      "name": "John Doe"
    }
  }'

Security Best Practices

PracticeWhy It Matters
Never expose keys in client codeAPI keys grant full access to your partner account. Keep them server-side only.
Use environment variablesStore keys in .env files or secrets managers, never in source code.
Rotate keys periodicallyGenerate new keys every 6-12 months to limit exposure risk.
Use separate keys per environmentDifferent keys for development, staging, and production isolate issues.
Revoke compromised keys immediatelyIf a key is exposed, revoke it in the dashboard and generate a new one.
Monitor API usageWatch for unexpected patterns that might indicate unauthorized access.

Frequently Asked Questions

While technically possible, we recommend generating separate API keys for development, staging, and production environments. This makes it easier to rotate keys and debug issues without affecting production traffic.
Immediately revoke the compromised key in Settings → API Keys and generate a new one. Update your integration with the new key. The old key will stop working immediately after revocation.
No! API keys should only be used from your backend servers. Exposing them in browser JavaScript would allow anyone to access your partner account and manage your customer organizations.
The /api/auth/login endpoint is used internally by the Answering Agent dashboard for user logins. As a partner, you use API keys with the /api/v1/* endpoints instead. You don’t need to worry about the login endpoint.
No. Simply include your API key in the X-API-KEY header. No additional signing or cryptographic operations are required.
Use embed tokens! After creating a customer organization, retrieve an embed token for the owner user and embed our dashboard in your application. See the Embed Guide for details.
Yes! You can generate multiple API keys and they will all work simultaneously. This is useful for key rotation (generate new key, update systems, then revoke old key) or for different services.

Next Steps

Now that you understand authentication, you’re ready to start building your integration:

Support

If you have questions about authentication or need help with your integration: