Skip to content
Developers

Get started

Authentication

API keys, live and test keys, and what each permission allows.

Send your key with every request

Every request carries an API key in the Authorization header. If your tool can’t set that header, X-API-Key works too.

http
Authorization: Bearer fz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A missing, wrong or revoked key gets 401 with the code UNAUTHORIZED. Too many wrong keys from one address in a minute are refused with 429 for the rest of that minute.

Live and test keys

  • fz_live_… keys send real SMS and are charged.
  • fz_test_… keys never send anything and are free. See Test mode.

Keys are always separate: going live means changing the key, not your code. Test keys only see test messages and live keys only see real ones.

Permissions

Each key can only do what was ticked when it was created. Calling something it can’t do gets 403 with MISSING_SCOPE, and the answer names the permission it needs. Give each system only what it uses: a shop that only sends order texts needs sms.send alone.

sms.sendpermission
Send SMS
sms.readpermission
Read SMS messages and their status
sender_ids.readpermission
Read sender IDs
templates.readpermission
Read SMS templates
balance.readpermission
Read the SMS balance

Keeping keys safe

  • Keep keys on your server, in environment variables or a secrets manager.
  • Never put a key in a website, a mobile app or a code repository.
  • Use one key per system, so you can revoke one without stopping the others.
  • If a key leaks, revoke it under API keys straight away; requests with it fail from that moment.
Falconzo stores only a fingerprint of each key, so a lost key can’t be shown again. Create a new one instead.