Authentication

Vonzio has three authentication mechanisms, each scoped to a different surface:

Mechanism	Used by	Header
API token (`rc_…`)	CLI, scripts, agents, third-party integrations	`Authorization: Bearer rc_…`
Better Auth session	Web dashboard (cookie)	`Cookie: better-auth.session_token=…`
Admin password	`/admin/*` endpoints	`Authorization: Bearer <password>`

All /v1/* endpoints accept both API tokens and Better Auth sessions; pick whichever fits.

API tokens

Tokens look like rc_<hex> and live in the api_tokens table, bcrypt-hashed. The plaintext is shown once at creation time and never recoverable — store it like an API key, not like a password.

Mint a token

Dashboard: Settings → API tokens → Create. Name it, copy the value, save it in your password manager.

API:

POST /v1/api-tokens
Authorization: Bearer <existing-token>  // or session cookie
Content-Type: application/json

{ "name": "morning-briefing-script" }

Response:

{
  "id": "tok_…",
  "name": "morning-briefing-script",
  "token": "rc_fb77d60732e06cc69f45489392f700a6637fee890c9c3bd0",
  "created_at": "2026-05-24T01:23:45.000Z"
}

The token field is the only chance to capture the plaintext.

Scope

API tokens inherit the full permissions of the user who created them. There’s currently no per-token scope — a token can access everything the user can. Rotate any token you’ve leaked.

(Future: per-token scope is on the roadmap.)

Rotation

To rotate:

Mint a new token.
Update your scripts / clients.
DELETE /v1/api-tokens/:id for the old one.

The platform doesn’t enforce expiry, but storing the last_used_at timestamp lets you spot stale tokens.

Better Auth sessions

The dashboard uses Better Auth for cookie-based sessions: email/password, Google OAuth, GitHub OAuth.

Endpoints under /api/auth/* are Better Auth’s surface (signup, signin, signout, session lookup). The dashboard handles these automatically — you rarely call them yourself unless building an alternative client.

GET /api/auth/get-session
Cookie: better-auth.session_token=…

Returns the session + user record.

Admin endpoints

/admin/* endpoints exist for platform operators only and aren’t relevant to most users. If you need admin access (e.g. to issue invites for additional users on your account), contact support.

Choosing a method

Building a CLI / cron script → API token.
Building an alternative web client → Better Auth (email/password + cookie).
Embedding in an agent’s custom tool → API token, stored in your Secrets vault.

Authentication errors

HTTP	Code	Meaning
401	`UNAUTHORIZED`	No credential provided, or credential rejected.
403	`FORBIDDEN`	Authenticated but not authorized for this resource.
404	`NOT_FOUND`	Resource lookup returned nothing — also used when ownership check fails to avoid leaking existence.

See Errors.