Authentication
Send a personal API key as a bearer token, and what each refusal means.
Every request carries a personal API key in the Authorization header. A key acts as the person
who created it, in the organization they had open when they created it, and sees exactly what that
person can open in VoiceCap.
Getting a key
Create one at Settings > Profile under API keys. The steps are on the
API keys page. VoiceCap shows the key once, when you create it. It
starts with vc_live_.
Sending it
curl -H "Authorization: Bearer $VOICECAP_API_KEY" https://voicecap.ai/api/v1/me
The header is the only place the API reads a key from. GET /me returns the person and
organization the key belongs to, which makes it a good first call to test a key and to label a
connection in an automation tool.
Treat a key like a password. Keep it in your tool's secret storage, not in source code, and revoke it at Settings > Profile if it may have leaked.
Which organization a key reads
A key belongs to one organization. It works while that organization is the one you have open in
VoiceCap. If you switch to another organization, the key answers 401 until you switch back. Keys
you create in the other organization work there.
When a key is refused
| Status | code | What it means |
|---|---|---|
| 401 | invalid_api_key | The key is wrong, revoked (resetting or changing your password revokes every key), belongs to an organization you've left or don't have open, or your account is deactivated. |
| 401 | unauthorized | There's no Authorization header, or its bearer token isn't an API key (API keys start with vc_live_). |
| 403 | api_keys_disabled | An Owner or Admin turned API keys off for your organization, or VoiceCap turned automations off for it. |
| 403 | email_not_verified | Your email address isn't verified yet. |
| 403 | org_suspended | Your organization is suspended. |
| 403 | api_key_not_allowed | The endpoint doesn't take API keys. Only the endpoints in the API reference do. |
| 403 | api_key_required | The endpoint takes only an API key, not a signed-in session. This applies to the /hooks endpoints. |
A 403 means the key itself is fine, so an automation tool shouldn't ask you to reconnect it. Fix
the cause instead.