Authentication

Every VoxelAI Studio endpoint authenticates the same way: a Bearer token in the Authorization header.

Authorization: Bearer YOUR_ACCESS_TOKEN

If the token is missing, expired, or invalid, the API returns 401 Unauthorized.

Self-serve developer tokens are on the way

Today there are two working token types (below). A general developer flow — where any account can mint and manage API tokens for its own apps from a dashboard — is rolling out. Until then, the only externally-usable credential is the vxlrbx_ Personal Access Token, obtained through the Roblox Studio device link.

Token types

Both are sent in the exact same Authorization: Bearer ... header; the server detects which one you sent.

1. Supabase session token

The short-lived JWT issued when a user signs in to the web app. The browser uses it for every in-app call. If you are developing against the app itself, you can read it from your session state. These tokens expire and must be refreshed by signing in again.

2. Personal Access Token (vxlrbx_…)

A long-lived token for programmatic clients — currently the Roblox Studio plugin. It looks like vxlrbx_ followed by a hex string. Only a SHA-256 hash of the token is stored server-side, so it is shown to you exactly once, at the moment it is minted. Treat it like a password.

You obtain a PAT through the device-link pairing flow — there is no password-style endpoint. See Roblox Studio for the full walkthrough, and revoke a token any time with POST /api/plugin/tokens/revoke.

Which endpoints accept which token?

The generation endpoints (/api/generate/*) accept both Supabase session tokens and vxlrbx_ PATs, so an integration can build models with a PAT. The account and billing endpoints (/api/tokens, /api/profile, /api/projects, /api/billing, /api/stripe/*) currently accept Supabase session tokens only.

Error codes

When a request is rejected for a reason beyond plain auth, the JSON body carries a machine-readable code alongside the HTTP status:

HTTP	code	Meaning
401	—	Missing, expired, or invalid token.
402	INSUFFICIENT_TOKENS	Authenticated, but out of tokens. Top up or upgrade.
402	ADULT_CONTENT_PAID_ONLY	Prompt flagged adult/violent; blocked for free plans.
403	NO_BALANCE	No token balance record exists for the account.
403	CONTENT_FLAGGED	Flagged content cannot be saved to the gallery.
422	EMPTY_MODEL	The agentic build produced nothing; the charge was refunded.
429	—	Rate limited (per-endpoint cooldown).

See Endpoints for which codes each route can return.