API Keys and Developer Access

Create API keys, understand scopes, rotate keys, rate limits, and access interactive API docs.

3 min readAccount & Billing

Creating API Keys

  1. Go to Settings > API Keys.
  2. Click Generate New Key.
  3. Enter a descriptive name (e.g., "CRM Integration", "Analytics Script", "Website Widget").
  4. Select the scopes the key needs (see below).
  5. Click Create.
  6. Copy the key immediately. It is shown only once. Store it in a secure location (password manager, environment variable, or secrets vault).

You can create up to 10 API keys per account. Use separate keys for separate integrations so you can revoke one without affecting others.

Understanding Scopes

Scopes control what each API key can access:

ScopePermissions
calls:readView call logs, transcripts, and analytics
calls:writeInitiate calls, update call settings
knowledge:readView knowledge base articles
knowledge:writeCreate, update, and delete articles
appointments:readView appointments
appointments:writeCreate, update, and cancel appointments
contacts:readView contacts
contacts:writeCreate, update, and delete contacts
account:readView account settings and team members
account:writeModify account settings, manage team
webhooks:manageCreate and manage webhook subscriptions

Principle of Least Privilege

Only grant the scopes an integration actually needs. For example:

  • A read-only analytics dashboard needs only calls:read.
  • A CRM integration that creates contacts needs contacts:write and calls:read.
  • A scheduling tool needs appointments:read and appointments:write.

Key Rotation Best Practices

Rotate your API keys regularly to maintain security:

  1. Create a new key with the same scopes as the old one.
  2. Update your integration to use the new key.
  3. Verify the integration works with the new key.
  4. Delete the old key.

Recommended Rotation Schedule

  • Production integrations: Every 90 days.
  • Development/testing keys: Every 30 days.
  • After a team member leaves: Immediately rotate any keys they had access to.

Emergency Revocation

If you suspect a key has been compromised:

  1. Go to Settings > API Keys.
  2. Click the trash icon next to the key.
  3. Confirm deletion.
  4. The key stops working immediately.
  5. Create a new key and update your integrations.

API Rate Limits

Rate limits prevent abuse and ensure fair usage:

PlanRequests per Minute
Starter60
Professional300
EnterpriseCustom (up to 3,000)

Rate Limit Headers

Every API response includes these headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1711700000
  • Limit: Your max requests per minute.
  • Remaining: How many requests you have left in this window.
  • Reset: Unix timestamp when the limit resets.

When You Hit the Limit

If you exceed the rate limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Best practice: Implement exponential backoff in your code.

Interactive API Docs

Visit [aivo.bz/api-docs](/api-docs) for the complete interactive API reference:

  • Browse all endpoints with descriptions.
  • Try requests directly in the browser.
  • See example request and response payloads.
  • Generate code snippets in JavaScript, Python, cURL, and more.

The API docs are always in sync with the latest version of the AIVO API.

Was this article helpful?

Previous
Understanding Your Bill