Skip to content
FoanFoanFoan Docs

API keys

An API key lets your own software talk to Foan: place calls, read results, add contacts to a campaign. Each key only does what you allow, and you can switch it off at any time.

You will need: a full login (logins limited to taking calls cannot open Developers), and somewhere safe to store the key, such as your server’s secret settings.

1. Create the key

Section titled “1. Create the key”

Open Developers > API Keys and press Create Secret Key. In New API Key, type a Key Display Name that says what uses it, for example “Booking system”.

2. Tick only the scopes it needs

Section titled “2. Tick only the scopes it needs”

Under Assign Scopes, tick what the key may do. Some common ones:

Scope Lets the key
calls:create Start calls.
calls:read Read call status, logs and history.
recordings:read Download call recordings.
campaigns:write Create campaigns and upload contacts.
campaigns:read Read campaigns, contacts and their results.
agents:read Read your agents’ settings.
knowledge:write Add and delete knowledge base documents.

A key for reports needs only calls:read and recordings:read. The API reference shows which scope each request needs.

3. Copy the key now

Section titled “3. Copy the key now”

Press Generate Key. Your secret key is shown once and will never be shown again. Copy it and store it somewhere safe, then tick the box to say you have stored it.

Your software sends it with every request as Authorization: Bearer <your key> to https://api.foan.ai/api/v1.

4. Revoke a key you no longer need

Section titled “4. Revoke a key you no longer need”

In the key list, open the menu at the end of the row and choose Revoke Key. Type REVOKE and press Revoke Forever. Anything using the key loses access straight away. Revoked keys stay listed under Revoked.

Common failures

Section titled “Common failures”
Generate Key says "Name must be at least 3 characters"

Make the Key Display Name at least 3 characters long.

Generate Key says "Select at least 1 scope"

Tick at least one scope under Assign Scopes.

I lost the key

A key is shown only once and cannot be recovered. Create a new key, update your software, then revoke the old one.

Requests with the key are refused

Check the key has the scope the request needs (the API reference lists it), and that it has not been revoked: look under Revoked.

Next steps

Section titled “Next steps”