Identity and access
Two keys, two surfaces
Section titled “Two keys, two surfaces”| Tenant key | Account key | |
|---|---|---|
| Issued by | us, at provisioning | tenant administrator |
| Opens | Tenant API | Account API |
| Reachable from | internal network only | public network |
| Can create accounts | yes | no |
| Can run calls | no | yes |
Issue keys with
POST/v1/internal/tenant/{sid}/api-keyand POST/v1/internal/account/{sid}/api-key.
Capability gates the action, scope gates the target
Section titled “Capability gates the action, scope gates the target”These are two independent checks and both must pass.
- Capability. May this role perform this kind of action at all? Deleting a scenario, issuing a key, dispatching a call.
- Scope. May this principal touch this particular object? Resolved from the principal, never from a header the caller controls.
A read of an object outside your scope answers 404, not 403. Returning 403 would
confirm the object exists, which is itself a leak.
Signing your users in
Section titled “Signing your users in”Voicebot supports two sign-in shapes. Neither asks your people to maintain a second password.
Magic link. Your system asks Voicebot for a one-time sign-in link for a user it already authenticated, then redirects the browser to it.
POST/v1/user/{sid}/magic-link/requestProvisioned credentials. Your system creates the user and drives a password reset, and the person signs in directly.
POST/v1/user/{sid}/password-reset/requestSession tokens
Section titled “Session tokens”Both API surfaces authenticate with a bearer token obtained from POST/v1/auth/regular. Tokens are short-lived. Refresh them rather than caching them for the lifetime of a process.
Feature flags
Section titled “Feature flags”Voicebot resolves what a tenant may use server-side and exposes it on the caller’s profile. Read the flags rather than hard-coding capability assumptions into your integration.
GET/v1/profileGET/v1/internal/tenant/{sid}/feature-flag