API Keys

API keys give programmatic access to Omniflow — for ingesting external transcripts, syncing your data warehouse, building custom workflows. Each key is scoped, rate-limited, and auditable.

Anatomy of a key

Field	Notes
Name	What it’s for — `data-warehouse-export`, `qa-ingest`, `crm-sync`.
Prefix	`omf_live_` or `omf_test_`.
Scopes	Which endpoints the key can hit.
Rate limit	Requests per minute / hour.
IP allowlist	Optional — restrict to specific source IPs.
Created by / at	Audit trail.
Last used	Timestamp; helps you find unused keys.

Create a key

Open API Keys

Settings → API Keys → New key.

Name it

Be specific. The name shows up in audit logs and dashboards.

Pick scopes

Scope to the minimum endpoints you actually need:

Scope	What it allows
`conversations:read`	GET conversations and traces.
`conversations:write`	POST conversations (transcript ingest).
`contacts:read` / `contacts:write`	Read or upsert contacts.
`tickets:read` / `tickets:write`	Read or write tickets.
`scorecards:read`	Pull QA scores.
`agents:read`	Read agent configs.
`webhooks:manage`	Configure webhooks programmatically.

Set a rate limit

Default is 60/min. For bulk exports, request a higher limit; for real-time integrations, the default is usually plenty.

Set IP allowlist (optional)

If your integration runs from a known IP range, lock the key to it.

Copy the secret — once

Omniflow shows the full key once. Copy it into your secrets manager immediately. You can rotate later but you can’t see it again.

Use a key


curl https://api.omniflow.example/api/v1/conversations \
  -H "Authorization: Bearer omf_live_xxxxxxxxxxxx"

Every API request returns:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

If you hit the limit, you’ll get 429 with a Retry-After header.

Rotate a key

Open the key

Settings → API Keys → [key name].

Click Rotate

Omniflow generates a new secret and gives you a 24-hour overlap period where both old and new are valid.

Update your integration

Swap the new secret in. Verify it works.

Revoke the old key

Once verified, click Revoke on the old version. The 24-hour overlap means a smooth swap with no downtime.

Rotate keys at least every 90 days. Build the rotation into your secret manager’s lifecycle — auto-rotated keys outlast forgotten ones.

Revoke a leaked key

If a key leaks (committed to git, posted in a PR, sent in a screenshot):

Settings → API Keys → [key] → Revoke immediately.
Audit the key’s last 30 days of usage in Settings → API Keys → Audit.
Generate a new key, update your integration.
If the audit shows suspicious activity, escalate per your incident response.

Test keys

Keys with the omf_test_ prefix work against a test view of your workspace. Useful for CI / staging.

Audit log

Every API call is logged with:

Key name.
Endpoint.
Status code.
Latency.
Source IP.
Argument hash (full payload available for 7 days).

Filter the audit log to find unusual patterns — sudden volume spikes, calls from unexpected IPs, repeated 4xx errors.

Integrations that connect via OAuth (Salesforce, HubSpot, Gmail) don’t use API keys. Those integrations have their own credential flow and don’t appear in this list.

Open in Omniflow

If you want to…	Go to
Read the API	API Reference
Wire webhooks	Custom API & Webhooks
See active integrations	Integrations overview