Authentication

VoxBridge uses two credential types: JWT bearer tokens for the dashboard and API, and long-lived sk_live_ keys for server-to-server integrations.

Dashboard authentication (JWT)

Human users authenticate via email and password. On login or signup, the API returns a short-lived JWT access token used for all /dashboard/* and /auth/me routes.

curl -X POST https://voxbridge.cc/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"jane@acme.com","password":"your-password"}'

Response:

{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer", "expires_in": 259200 }

Include the token on subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

JWT claims

Tokens are signed with HS256 and include:

sub — user UUID
org_id — organization UUID (tenant scope)
role — owner, member, or platform_admin
type — must be dashboard (API keys cannot be exchanged for dashboard tokens)
exp — expiration (default 72 hours, configurable via JWT_EXPIRE_HOURS)

Expired or tampered tokens receive 401 Unauthorized. Inactive users or organizations receive 403 Forbidden.

API key authentication

Integrations and backend services should use organization API keys, not user passwords. Keys are sent as Bearer tokens on /v1/* endpoints.

Authorization: Bearer sk_live_abc123...

Key format

Prefix: sk_live_ — required; other formats are rejected.
Storage: Only a SHA-256 hash and a 16-character prefix are stored server-side.
Display: The full secret is shown once at creation (signup or POST /dashboard/api-keys).

Managing keys

Action	Endpoint	Auth
List keys	`GET /dashboard/api-keys`	JWT
Create key	`POST /dashboard/api-keys`	JWT
Revoke key	`POST /dashboard/api-keys/{id}/revoke`	JWT

Security best practices

Never embed API keys in client-side JavaScript, mobile apps, or public repositories.
Rotate keys immediately if exposed; revoke the old key via the dashboard.
Use separate keys per environment (staging vs production) when you create named keys.
Restrict dashboard JWTs to browser sessions; use API keys for cron jobs, webhooks receivers, and CRM integrations.
Verify webhook payloads with X-Voice-Signature (see Webhooks).

Platform admin

Users with role platform_admin or an email listed in PLATFORM_ADMIN_EMAILS can access /api/admin/* routes for cross-tenant operations. This is separate from organization owner access.

Quick start → · API reference →