Authentication
Your own code uses an API key. Apps and AI assistants that other people connect use OAuth, so nobody has to copy a key. Both get the same access, limited by scopes.
API keys
Create keys in ListenFox under Settings → API keys. You need the owner or admin role. Step by step
- Give each key a name, such as “Zapier” or “Nightly report”, and pick a preset.
- The key is shown once, when you create it. It starts with
lf_live_. We store only a fingerprint of it (a hash), so we can’t show it again. - The list shows the start of each key, when it was last used and what it can do.
- A key belongs to one workspace. To reach several workspaces, create a key in each.
- Revoke a key at any time. It stops working straight away. Creating and revoking keys is recorded in the audit log.
Sending the key
Send the key in the Authorization header of every request:
curl "https://listenfox.com/api/public/v1/me" \
-H "Authorization: Bearer lf_live_..."If a tool can only set a custom header, send X-API-Key: lf_live_... instead. Never put the key in the URL.
Presets
A preset is a ready-made set of scopes. Pick the smallest one that does the job.
| Preset | Scopes | Good for |
|---|---|---|
| Read only | calls:readcontacts:readfollowups:readinsights:read | Reports, dashboards and copying calls into a sheet or a CRM. |
| Automations | Read only, plus calls:writecontacts:writefollowups:writewebhooks | n8n, Zapier, Make and your own sync jobs: they react to events and write follow-ups, labels and contact fields. |
| Full | Automations, plus askanalyze | Everything, including the two things that use credits. |
Scopes
Each route in the API reference names the scope it needs. A key without it gets a 403 with the code insufficient_scope. GET /me and GET /meta work with any key.
| Scope | What it allows |
|---|---|
calls:read | List calls and read each one: summary, transcript, key moments and findings. |
calls:write | Add calls, and add or remove labels on them. |
contacts:read | List and read contacts, the people who call you. |
contacts:write | Change a contact’s name, email, status and custom fields. |
followups:read | List follow-ups. |
followups:write | Create follow-ups and mark them done. |
insights:read | Read metrics, top objections, unmet demand and team member scorecards. |
ask | Ask questions about your calls. Uses 1 Ask credit a question (AI credits once those run out). |
analyze | Analyze calls. Uses 2 credits a call on Standard (1 on Quick, 4 on Deep). |
webhooks | Create, list and delete webhooks, and read recent events. |
No key can delete calls or contacts, or change what ListenFox found in a call. Those stay in the app.
Keeping keys safe
- Use keys only in code that runs on a server. Never put one in a web page, a mobile app or a public code repository.
- Use one key per tool, so you can revoke one without breaking the others.
- If a key leaks, revoke it in Settings and create a new one. Nothing else needs to change.
OAuth for apps and AI assistants
OAuth lets someone connect an app to ListenFox by signing in and clicking Allow, instead of copying a key. Claude, ChatGPT and Cursor connect to the MCP server this way. If you’re building an app for other ListenFox customers, use it too.
What the person sees
They sign in, pick the workspace, see the access your app asks for in plain words, choose a preset and click Allow or Deny. Anyone in a workspace can connect an app with Read only, and it sees the same calls they do. Automations and Full need an admin. They can disconnect it at any time under Settings → Connected apps.
For app builders
- Discovery:
https://listenfox.com/.well-known/oauth-authorization-serverlists every endpoint, andhttps://listenfox.com/.well-known/oauth-protected-resourcedescribes the API. - Register your app with one request to
https://listenfox.com/api/oauth/register(Dynamic Client Registration, RFC 7591). There’s no form to fill in. - Only the authorization code flow with PKCE (method
S256) is supported. PKCE is a one-time secret your app makes for each sign-in, so a stolen code is useless on its own. - The redirect URI must match a registered one exactly. It must use https, except for loopback addresses (localhost) used by desktop apps.
- Ask for scopes in
scope, separated by spaces. The consent screen starts on the smallest preset that covers them, and the person can change it. - Codes last 10 minutes and work once. Access tokens last 1 hour. Refresh tokens last 30 days and change every time you use one: keep the new one and drop the old.
- An access token works everywhere an API key does, in the same
Authorization: Bearerheader. Revoke tokens athttps://listenfox.com/api/oauth/revoke.
https://listenfox.com/api/oauth/authorize?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fyourapp.example%2Fcallback
&scope=calls%3Aread%20contacts%3Aread
&state=RANDOM_STATE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256curl -X POST "https://listenfox.com/api/oauth/token" \
-d grant_type=authorization_code \
-d code=THE_CODE \
-d redirect_uri=https://yourapp.example/callback \
-d client_id=YOUR_CLIENT_ID \
-d code_verifier=CODE_VERIFIERThe answer has access_token, expires_in (3600 seconds), refresh_token and the granted scope. To refresh, post grant_type=refresh_token with the refresh token and your client_id.