API Keys and Authentication#
Supafone authentication and S2S model credentials#
Your Supafone API key authenticates your app to Agent Factory. It is different from the server-side OpenAI, Google, xAI, or Smallest AI key used by the selected speaking model. Supafone uses its configured platform key unless the account has an encrypted BYOK override for that provider. Customers need no separate vendor key when managed credentials are available.
Use GET /api/v1/labs/runtime?provider=openai (or google, xai, smallest) to inspect credential source and readiness without exposing the secret. Model access and carrier routing still need live verification. See Native S2S credentials.
One key does everything. A single sl_live_... Labs key authenticates Labs Cloud, the whole Supafone product API, the MCP server, and both SDKs — as long as you have confirmed the email on the key and an app.supafone.ai account exists with that same email. Set export SUPAFONE_TOKEN=sl_live_... and you are done; there is no second key to provision. Legacy scoped sf_live_... keys still work for hosted-agent-only use, but they are the exception, not the default.
One key covers both surfaces:
| Key | Base URL | Used for |
|---|---|---|
sl_live_... | https://api.labs.supafone.ai and https://api.supafone.ai | Everything: Labs Cloud oracle, TTS, STT, logs, usage, builder, QA, optimizer — plus the whole product API (campaigns, calls, agents) via one-key auth |
sf_live_... (legacy) | https://api.supafone.ai/api/v1/labs | Optional scoped key for hosted-agent-only use — the sl_ key already covers this surface |
One Key, Both APIs#
An sl_ key is no longer labs-only. The Supafone product API (https://api.supafone.ai) accepts it as a bearer credential anywhere an account JWT works: on first use it introspects the key against GET https://api.labs.supafone.ai/v1/keys/introspect, checks that the key's email has been confirmed, maps that email to your app.supafone.ai account, and caches the validated key in-process for ~5 minutes. Anything doubtful — unknown key, deactivated key, unconfirmed email, labs outage — fails closed as a 401, never a fallback.
export SUPAFONE_TOKEN=sl_live_... # ONE env var: MCP + both SDKs, end to end
curl https://api.supafone.ai/api/v1/campaigns \
-H "Authorization: Bearer $SUPAFONE_TOKEN"Requirements:
- The key's email must be confirmed (see Confirm your email).
- An app.supafone.ai account must exist with the same email that owns the
- The key must be active in the labs console.
- The address must not be a Supafone platform admin. Admin addresses sign in at
Until then the product API answers 401 and says how to confirm.
key — otherwise the API answers 401 with "create an app.supafone.ai account with the same email".
app.supafone.ai only, so their keys are refused here even when confirmed.
Account login (email/password or JWT) keeps working exactly as before — the sl_ path is additive.
Confirm Your Email#
A key is only as good as the proof behind its email, so anyone holding a key has to show they also control that mailbox. We email an 8-digit code, and you enter it once:
# Ask for a code (signing up sends the first one for you)
curl -X POST https://api.labs.supafone.ai/v1/auth/confirm/send \
-H "Authorization: Bearer $SUPAFONE_LABS_API_KEY"
# Enter it
curl -X POST https://api.labs.supafone.ai/v1/auth/confirm \
-H "Authorization: Bearer $SUPAFONE_LABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code":"12345678"}'Or sign in at the console, which asks for the code. Codes last 15 minutes and stop working after 5 wrong tries.
What confirming changes:
- The key you confirmed with works on the product API.
- A new account gets its five free minutes.
- Any other key already on the account stops working until you confirm it from
- If you confirm with anything but your password, any existing password stops
the console's key list. If you don't recognize one, disable it instead.
working and other sessions are signed out, because it may not have been yours. Set a new one with POST /v1/auth/change-password.
Keys created from a confirmed console session are confirmed from the start. Before you confirm, a console session reaches only this step.
Labs Cloud Auth#
Create a trial key for a new email. An email that already has an account gets a 409 and no key; sign in instead, or ask for a sign-in code with POST /v1/auth/confirm/send and {"email": "..."}.
curl -X POST https://api.labs.supafone.ai/v1/signup \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com"}'We email a code to that address. Confirm it to start your five free minutes.
Use it as a bearer token:
curl https://api.labs.supafone.ai/v1/usage \
-H "Authorization: Bearer $SUPAFONE_LABS_API_KEY"The TypeScript SDK uses this key as apiKey for Labs Cloud methods:
const supafone = new Supafone({
apiKey: process.env.SUPAFONE_LABS_API_KEY!,
});Legacy Scoped Hosted-Agent Keys#
Your one sl_ key already authenticates the hosted-agent API via one-key auth, so most integrations never need a second key:
curl https://api.supafone.ai/api/v1/labs/capabilities \
-H "Authorization: Bearer $SUPAFONE_LABS_API_KEY"For hosted-agent-only deployments you can still mint a scoped sf_live_... key from the Supafone account-admin flow. It is the exception, not the default.
The hosted-agent API also accepts x-supafone-key and x-supafone-api-key, but bearer auth is the recommended default.
The recommended TypeScript setup for every public surface is one token:
const supafone = new Supafone({
apiKey: process.env.SUPAFONE_TOKEN!,
});Separate per-surface credentials remain an advanced compatibility option for teams that deliberately want scoped keys:
const supafone = new Supafone({
apiKey: process.env.SUPAFONE_LABS_API_KEY!,
supafoneApiKey: process.env.SUPAFONE_API_KEY!,
});Creating Hosted-Agent Keys#
Hosted-agent key management is an account-admin operation on the Supafone app API. It uses the normal app user session or JWT, not the hosted-agent key being created.
POST /api/v1/labs/api-keys
GET /api/v1/labs/api-keys?agency_id=...
DELETE /api/v1/labs/api-keys/{key_id}?agency_id=...Create body:
{
"agency_id": "00000000-0000-0000-0000-000000000000",
"name": "Production key",
"scopes": [
"agents:write",
"agents:read",
"voices:read",
"calls:write",
"numbers:read",
"numbers:write",
"telephony:read",
"telephony:write"
]
}The raw sf_live_... value is returned once. List and revoke responses should only expose prefixes or metadata.
Console Sessions#
Labs Cloud also supports account sessions for console-scoped features:
POST /v1/auth/register
POST /v1/auth/login
POST /v1/auth/key-login
POST /v1/auth/confirm/send
POST /v1/auth/confirm
GET /v1/account
POST /v1/account/keys
PATCH /v1/account/keys/{key}
POST /v1/account/keys/{key}/confirmBuilder and QA methods require a session token. Most read and usage endpoints accept either a session token or an sl_live_... key.
Key Hygiene#
- Never commit
sl_live_...,sf_live_..., provider keys, Twilio credentials, - Use environment variables in examples, tests, and deploys.
- Show only masked keys in dashboards and logs.
- Rotate keys when they leave the intended environment.
Stripe secrets, or admin secrets.