Authentication
Bearer tokens, personal access tokens, device login, and scopes.
Every API call is authenticated with a bearer token:
Authorization: Bearer <token>There are two kinds of tokens, both sent the same way.
Personal access tokens (PATs)
Best for scripts, CI, and servers.
- Created in the Studio under Settings → API tokens.
- Shaped
blit_…. The full token is shown exactly once at creation — Blitflow stores only a hash and cannot show it again. - Optional expiry, up to 365 days.
- Revocable at any time from the same settings page.
Treat a PAT like a password: keep it in an environment variable or secret manager, never in source control.
Device login (OAuth device flow)
Best for a developer's own machine. The CLI signs you in through
the browser and saves a short-lived session token to
~/.blitflow/config.json:
blitflow loginFor CI and headless environments, set BLITFLOW_TOKEN (a PAT) instead of
logging in.
The MCP hosted server uses the same OAuth machinery — MCP clients authenticate interactively, no token pasting required. See MCP server.
Base URLs
| Client | Base URL |
|---|---|
| Public API | https://studio.blitflow.com/api |
| A Studio deployment directly | https://<studio-host>/api (the API is served under the /api prefix) |
Contract paths are relative to the base: /v1/nodes is
https://studio.blitflow.com/api/v1/nodes, or https://<studio-host>/api/v1/nodes
when calling a Studio host directly.
The SDK defaults to https://studio.blitflow.com/api when you pass an apiKey, and
accepts a baseUrl override — see SDK setup.
Scopes
Each operation has a scope. Tokens act on behalf of your user account:
| Scope | Operations | Effect |
|---|---|---|
read | nodes.list, nodes.get, workflows.get | No cost, no side effects |
run | runs.create, runs.node | Executes nodes — spends money |
Runs accept a maxCostUsd cap, and the server enforces its own ceiling on top.
See Runs & streaming.
Errors
| Status | Meaning |
|---|---|
401 | Missing, invalid, expired, or revoked token |
403 | Authenticated but not allowed (e.g. cross-origin cookie request) |
Error bodies are JSON: { "error": "<message>" }.
Browser sessions (cookies) also work against the API for same-origin calls from the Studio itself, but API clients should always use bearer tokens — cookie auth is CSRF-guarded and rejects cross-origin mutations.