Authentication
API keys, scopes, the header, and auth errors.
Every request to /v1 carries an API key as a bearer token:
GET /v1/actions HTTP/1.1
Host: api.venehealth.com
Authorization: Bearer <api_key>API keys
Vene issues each key to your organization and shows it once. A key looks like
vak_ followed by an 8-character prefix and a secret part. Vene stores only
the prefix and a hash of the key, so a lost key cannot be recovered. Ask Vene
for a new one and have the old one revoked.
Keep keys on your server. Never ship one in a browser, a mobile app, or a prompt a model can read back.
Every action, call, transcript, and patient belongs to the organization whose
key created it. Another organization's IDs read as 404 not_found.
Scopes
A key holds one or both scopes:
| Scope | Allows |
|---|---|
| Actions read | GET requests: retrieve and list actions, events, and transcripts. |
| Actions write | Everything else: create, answer, and cancel. |
Errors
| Status | Code | When |
|---|---|---|
401 | unauthorized | The Authorization header is missing, malformed, or names an unknown or revoked key. |
403 | forbidden | The key lacks the scope this request needs. |
{
"error": {
"code": "unauthorized",
"message": "A valid API key is required"
}
}Your organization also has a request rate and a limit on running actions. See Limits and idempotency.