API Keys
API keys authenticate external access to VocaLoop — the Secure Link Loop API, whether you call it yourself or through a voice-agent platform such as Vapi. Your browser session (login cookie) never leaves the app; anything that talks to VocaLoop from outside uses a key.
Keys live inside a project. Every key belongs to exactly one project and can only ever touch that project — any other project id returns 404, exactly as if it didn't exist. There are no account-wide keys; give each consumer a key created in the project it works with.
Creating a key
Open the project in the sidebar and go to its API Keys page (
/projects/<id>/api-keys), then click Add API Key.Name the key after what will use it (e.g.
zapier,claude-desktop,crm-sync) and tick the actions it needs.The full secret —
vlk_followed by 32 random characters — is shown once, at creation time (keys created before the VocaLoop rename start withdbk_and keep working). Copy it immediately; only a hash is stored, so it can never be displayed again. The list shows just the first 12 characters (the prefix) for identification.
Actions
Every key carries an explicit list of allowed actions. New keys start with both; narrow them per key (at creation or later via Edit actions). Calling an endpoint without its action returns 403 with the missing action named.
| Action | Allows |
|---|---|
| Send loops (default) | POST /api/external/loop/send-secure-link — generate the project's form from a prompt and send its fill link on WhatsApp, email or text; also what a Vapi tool needs. The same grant covers POST /api/external/send-wa-loop (ask a question or run a plan on WhatsApp — see the WhatsApp Reply Loop API) and POST /api/external/send-wa-form (send the form to fill in inside WhatsApp — see the WhatsApp Form Loop API) |
| Read loop status (default) | GET /api/external/loop/{request_id} — poll a loop and read the response with its analytics, or a WhatsApp question's reply (one endpoint for both) |
Keys minted by the Getting Started wizard for a vendor tool carry only Send loops — the tool never reads responses.
Using a key
Send it in either header (both are accepted everywhere keys work):
curl http://localhost:3000/api/external/loop/<request_id> -H "X-API-Key: vlk_..."
# or
curl http://localhost:3000/api/external/loop/<request_id> -H "Authorization: Bearer vlk_..."Managing keys
| Action | Effect |
|---|---|
| Edit actions | Change what the key may do — takes effect immediately |
| Deactivate | The key stops working immediately (requests get 401) but keeps its action grants — reactivate to restore it. Use this to pause a consumer without reconfiguring it |
| Delete | Permanent; requests get 401. Deleting the project deletes its keys too |
| Last used | Each key shows when it last authenticated a request — handy for spotting dead keys before deleting them |
Security notes
Treat a key like a password: it can send messages to real people through your integrations. Don't commit keys or embed them in client-side code.
Keys are high-entropy and stored as SHA-256 hashes; a database leak doesn't reveal usable secrets.
Grant only the actions a consumer needs — a send-only integration has no reason to read responses.
Rotate by creating a new key with the same actions, switching the consumer over, then deleting the old key.
An invalid, deactivated, or deleted key gets the same
401— callers can't probe which keys exist. A valid key without an action gets403.