Authentication
Every request carries an API key in the Authorization header.
Authorization: Bearer vf_test_xxxxxxxx_PASTE_THE_REST_OF_YOUR_KEYKey format
| Key | Use |
|---|---|
vf_live_xxxxxxxx_… | Secret key, real leads |
vf_test_xxxxxxxx_… | Secret key, sandbox |
vf_live_pub_xxxxxxxx_… | Public key, real leads |
vf_test_pub_xxxxxxxx_… | Public key, sandbox |
The 8 characters after the type are the key's prefix. They are safe to show and help you tell keys apart. The rest is the secret.
Public keys
Made for browser forms. They can only create leads, only from the websites listed as allowed origins on the key (https://example.com or https://*.example.com; test keys may also use http://localhost). Each submission needs a captcha token, and spam checks apply.
Secret keys
Made for servers. Never put them in browser or app code. You can limit them to a list of IP addresses. What they may do depends on their scopes:
| Scope | Allows |
|---|---|
leads:create | Create leads |
leads:read | List and read leads |
leads:update | Update leads and add notes |
applications:read | Read application status |
webhooks:manage | List, create and delete webhook endpoints |
Rotate and revoke
Rotating a key gives you a new secret right away while the old one keeps working for 24 hours, so you can update your servers without downtime. Revoking stops the key at once.
When a key is refused
| Status | Code | What to do |
|---|---|---|
| 401 | invalid_api_key | The key is missing, wrong, revoked or expired. |
| 403 | insufficient_scope | The key lacks the scope this endpoint needs. The body names it in required. |
| 403 | origin_not_allowed | A public key was used from a website that is not on its list. |
| 403 | ip_not_allowed | A secret key was used from an address that is not on its list. |
| 402 | tenant_suspended | The workspace's subscription is not active. |
Keys only work on the API host. Signed-in staff sessions do not work here, and keys do not work in the VisaFlow app.