Developer docs: Authentication

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.

Send the key in the Authorization header of every request:

Terminal
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.

PresetScopesGood for
Read onlycalls:readcontacts:readfollowups:readinsights:readReports, dashboards and copying calls into a sheet or a CRM.
AutomationsRead only, plus calls:writecontacts:writefollowups:writewebhooksn8n, Zapier, Make and your own sync jobs: they react to events and write follow-ups, labels and contact fields.
FullAutomations, plus askanalyzeEverything, 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.

ScopeWhat it allows
calls:readList calls and read each one: summary, transcript, key moments and findings.
calls:writeAdd calls, and add or remove labels on them.
contacts:readList and read contacts, the people who call you.
contacts:writeChange a contact’s name, email, status and custom fields.
followups:readList follow-ups.
followups:writeCreate follow-ups and mark them done.
insights:readRead metrics, top objections, unmet demand and team member scorecards.
askAsk questions about your calls. Uses 1 Ask credit a question (AI credits once those run out).
analyzeAnalyze calls. Uses 2 credits a call on Standard (1 on Quick, 4 on Deep).
webhooksCreate, 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-server lists every endpoint, and https://listenfox.com/.well-known/oauth-protected-resource describes 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: Bearer header. Revoke tokens at https://listenfox.com/api/oauth/revoke.
Send the person to sign in
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=S256
Swap the code for tokens
curl -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_VERIFIER

The 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.