Authentication

VOL accepts two kinds of credentials. Both are sent on every request; there is no cookie-based auth.

	User session	API key
Header	Authorization: Bearer <access_token>	X-API-Key: vol_live_…
Issued by	Supabase Auth (email, Google, magic link, SSO)	The app’s Developer → API keys, or POST /v1/keys
Represents	A signed-in person	Your integration
Lifetime	~1 hour, refreshed by Supabase	Until revoked
Use in	The VOL app and first-party UIs	Backends, SDK scripts, embeds, CI

Public endpoints

GET /v1/health, GET /v1/cases and POST /v1/docs/ask need no credentials.

API keys

Create your first key from the app (or with a user session). Keys belong to the user who created them, so any of that user’s credentials can list, create or revoke them:

cURL

curl -X POST https://vol.example.com/api/v1/keys \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"production backend"}'

TypeScript

const vol = new VolClient({ accessToken: session.access_token });
const { key, prefix } = await vol.keys.create("production backend");
// store `key` securely — it is never shown again

The response includes the full key once. VOL stores only a hash and shows the prefix afterwards, so you can recognise keys in the list. Revoke a key with DELETE /v1/keys/{id}; requests using it fail with 401 immediately.

Keys in the browser

Anything shipped to a browser is public. For embeds, create a dedicated key per site so you can revoke it independently, and keep high-privilege keys on your server.

User sessions (Supabase)

The VOL app signs users in with Supabase and forwards the session’s access_token. vol-api verifies the JWT against the project’s JWKS. With the SDK, pass a function so a refreshed token is used on each call:

import { createClient } from "@supabase/supabase-js";
import { VolClient } from "@vol/sdk";

const supabase = createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY);
const vol = new VolClient({
  accessToken: async () => (await supabase.auth.getSession()).data.session?.access_token,
});

const me = await vol.me(); // { id, email }

Errors

Status	error.code	Meaning
401	unauthorized	No credentials sent
401	invalid_api_key	Unknown or revoked API key
401	invalid_token, token_expired	Supabase token malformed, from another project, or expired
429	rate_limited	Too many requests per minute for this key or user

See Errors for the error envelope.

Acting on behalf of users

Third-party apps that need to act for a VOL user will use the OAuth client flow (coming soon) instead of handling Supabase tokens directly.