API Keys
API keys authenticate external access to VocaLoop — the External API and vendor platforms. 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 Generate & send and Send; grant the rest per key (at creation or later via Edit actions). Calling an endpoint without its action returns 403 with the missing action named.
| Action | Allows |
|---|---|
| Generate & send (default) | POST /external/projects/generate-send and the Vapi vendor endpoint — regenerate the project from a prompt and WhatsApp its fill link |
| Send (default) | POST /external/projects/{id}/send — deliver fill requests over the configured channels |
| Check status | GET /external/requests — poll requests and read submitted responses |
| Submit data | POST /external/projects/{id}/submissions — push submissions directly into the project |
| Read project | GET /external/projects[/{id}] — read the project's details |
Using a key
Send it in either header (both are accepted everywhere keys work):
curl http://localhost:3000/api/v1/external/projects -H "X-API-Key: vlk_..."
# or
curl http://localhost:3000/api/v1/external/projects -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.