Authentication

All ioZen API requests require authentication via API keys sent as Bearer tokens.

API Keys

API keys are workspace-scoped credentials that grant programmatic access to your ioZen data. Keys are available on Pro and Business plans.

Key Format

Keys follow the format iozen_live_ followed by a cryptographically random string:

iozen_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456

The iozen_live_ prefix makes keys identifiable in logs, git scanners, and secret detection tools.

Using Your Key

Include the key in the Authorization header of every request:

curl https://app.iozen.ai/api/v1/intake-bots \
  -H "Authorization: Bearer iozen_live_your_key_here"

const response = await fetch('https://app.iozen.ai/api/v1/intake-bots', {
  headers: {
    Authorization: `Bearer ${process.env.IOZEN_API_KEY}`,
  },
});

Scopes

Each API key is assigned one or more scopes that control what it can access. Follow the principle of least privilege — only grant the scopes each integration needs.

Scope	Description
`read:intake-bots`	List and read intake bots
`write:intake-bots`	Create submissions and update intake bots
`read:submissions`	List and read submissions
`read:contacts`	List and read contacts
`read:records`	List and read records
`manage:webhooks`	Create and manage webhook endpoints

If a request requires a scope your key doesn't have, you'll receive a 403 response with an insufficient_scopes error code. The response includes which scopes are required and which your key has:

{
  "success": false,
  "error": {
    "code": "insufficient_scopes",
    "message": "API key lacks required scopes for this endpoint",
    "details": {
      "required": ["read:submissions"],
      "granted": ["read:intake-bots"]
    }
  }
}

Rate Limits

Rate limits are enforced per API key using a sliding window, based on your plan:

Plan	Requests per Minute	Max API Keys
Free	—	0 (API access not available)
Pro	100	3
Business	500	10

Rate limit information is included in every response via headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp (milliseconds) when the window resets

When rate limited, you'll receive a 429 response. See the Rate Limits guide for retry strategies.

Key Management

Creating Keys

Create keys from Workspace Settings → API Keys. Only workspace Owners and Admins can manage API keys. When you create a key, the full key is shown once — copy it immediately.

Revoking Keys

Revoke a key immediately if it's compromised. Revoked keys stop working within 60 seconds (due to a short-lived cache). To revoke:

Go to Workspace Settings → API Keys
Click the Revoke button next to the key
Confirm the action

Revocation is permanent — you cannot un-revoke a key.

Key Expiration

Keys can optionally have an expiration date set at creation time. Expired keys are automatically rejected. Use expiration dates for temporary integrations or contractor access.

Monitoring Usage

Each key's last usage time is displayed in the key list. Use this to identify unused keys that should be revoked.

Security Best Practices

Never commit API keys to source control. Use environment variables or a secrets manager.
Use the minimum scopes needed. A read-only integration should not have write:intake-bots.
Rotate keys periodically. Create a new key, update your integration, then revoke the old key.
Revoke unused keys. If an integration is decommissioned, revoke its key immediately.
Set expiration dates for temporary or contractor integrations.
Monitor the last_used_at timestamp to detect unauthorized usage patterns.

Every API response includes an X-Request-Id header with a unique identifier. Include this ID when contacting support about a specific request — it allows us to quickly locate the request in our logs.