API keys and authentication

Draft — written from product facts + domain knowledge; UI labels to be verified before publishing.

The OutreachFox API lets you create campaigns, push leads, read replies and manage mailboxes from your own code. Every request is authenticated with an API key that belongs to one workspace. This article shows where to create keys, how to send them, how to stay inside rate limits and how to rotate a key safely.

Prerequisites

• You are an Owner or Admin of the workspace. Members and Client viewers cannot create keys.
• You know which workspace the key should belong to. A key only reaches the campaigns, contacts and mailboxes of the workspace it was created in.

Steps

1. Click Settings in the bottom-left corner of the left nav.
2. Open the Integrations tab and click API Keys.
3. Click Create API Key.
4. Enter a Name that says where the key will be used, for example zapier-prod or crm-sync.
5. Choose the Scope. Use Read only for reporting and dashboards; use Read and write only when the integration needs to create leads, campaigns or webhooks.
6. Click Create. The full key is shown once. Copy it into your secrets manager now; after you close the dialog only the last four characters are visible.
7. Send the key in the Authorization header of every request:

GET https://api.outreachfox.com/v1/campaigns

Authorization: Bearer of_live_xxxxxxxxxxxxxxxxxxxx

Content-Type: application/json

1. Check the response. A 200 with a JSON body means the key works. 401 Unauthorized means the key is missing, malformed or revoked; 403 Forbidden means the key's scope does not allow the action.

After the key is created it appears in the API Keys list with its name, scope, creation date and Last used timestamp. Use Last used to find keys that are no longer needed.

Rate limits and etiquette

• The default limit is 60 requests per minute per API key, with bursts of up to 10 requests per second. The response headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset tell you where you stand.
• When you receive 429 Too Many Requests, wait for the number of seconds in the Retry-After header and retry with exponential backoff (1 s, 2 s, 4 s, up to 60 s). Do not retry in a tight loop.
• Use bulk endpoints where they exist. POST /v1/leads/bulk accepts up to 1,000 leads per call and costs one request, not one thousand.
• Poll no more often than every 60 seconds. For anything event-driven (replies, bounces, unsubscribes), use webhooks instead of polling. See "Webhooks: events, payload examples and retries".
• Paginate with the cursor parameter and a limit of 100 or less.

Key rotation

Rotate a key every 90 days, whenever a team member with access leaves, and immediately if a key is pasted into a ticket, a chat or a public repository.

1. Create a new key with the same name plus a suffix, for example crm-sync-2.
2. Deploy the new key to the integration.
3. Confirm the new key's Last used timestamp updates.
4. In Settings → Integrations → API Keys, click the three dots next to the old key and choose Revoke. Revocation is immediate and cannot be undone.

Tips

• Create one key per integration. If one key leaks, you only revoke that one.
• Never put a key in a URL query string; it ends up in server logs.
• Store keys in environment variables or a secrets manager, never in front-end code.
• Keys for a test workspace are prefixed of_test_; production keys are prefixed of_live_. Check the prefix when a request unexpectedly returns empty data.

Troubleshooting

• 401 on every request: check for a trailing space or missing Bearer prefix in the header.
• 403 on a write: the key was created with Read only scope. Create a new key with Read and write; scope cannot be changed after creation.
• Empty lists: the key belongs to a different workspace than the one you are looking at in the app.
• Sudden 429s: another process is sharing the same key. Give each process its own key.

Related articles

• Webhooks: events, payload examples and retries
• Connect OutreachFox to Zapier and Make
• OutreachFox MCP server: use OutreachFox from Claude, Cursor and other AI agents
• Create workspaces, invite members and set roles
• Security: two-factor authentication, sessions and audit logs