Browse the docs
Documentation

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

StatuscodeWhat it means
401invalid_api_keyThe 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.
401unauthorizedThere's no Authorization header, or its bearer token isn't an API key (API keys start with vc_live_).
403api_keys_disabledAn Owner or Admin turned API keys off for your organization, or VoiceCap turned automations off for it.
403email_not_verifiedYour email address isn't verified yet.
403org_suspendedYour organization is suspended.
403api_key_not_allowedThe endpoint doesn't take API keys. Only the endpoints in the API reference do.
403api_key_requiredThe 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.