Authentication

Tokens, sessions, the CLI device flow, and workspace scoping.

Auth methods

Floom Cloud accepts three credentials. Pick one by where your code runs.

API tokenheader

A long-lived token sent as x-floom-token. The right choice for scripts, servers, CI, and MCP clients. Personal (floom_…) or workspace-scoped (wst_…).

Session JWTheader

A short-lived Supabase access token sent as Authorization: Bearer. Used by the dashboard; expires hourly and must be refreshed. Rarely what you want for automation.

Device flowinteractive

A browser-approved pairing the CLI uses to obtain a token without you copy-pasting one. See CLI device flow.

Recommendation

For anything non-interactive, use an API token. It does not expire, carries a default workspace, and is the simplest header to set.

Personal & workspace tokens

Tokens are sent in the x-floom-token header. There are two kinds:

Personal access token (floom_…) — tied to your user, valid across every workspace you belong to. Mint in the dashboard under Settings → API tokens, or via the API.
Workspace token (wst_…) — tied to one workspace, ideal for shared automation that should not follow a single person’s account.

request

curl https://workeros-api.floom.dev/api/workers \
  -H "x-floom-token: floom_xxxxxxxxxxxxxxxxxxxxxxxx"

Manage tokens over the API:

GET/auth/tokens

List your personal tokens (prefix + metadata only; the secret is shown once at creation).

POST/auth/tokens

Create a personal token. Returns the full floom_… value once — store it now.

DELETE/auth/tokens/{token_id}

Revoke a personal token. Takes effect within ~60s (tokens are cached briefly).

GET/api/workspace/tokens

List workspace tokens.

POST/api/workspace/tokens

Create a workspace token (wst_…).

DELETE/api/workspace/tokens/{token_id}

Revoke a workspace token.

Treat tokens like passwords

A token grants full API access to its workspace(s). Store it in a secret manager, never commit it, and revoke immediately if leaked. Revocation propagates within ~60 seconds.

CLI device flow

floom login --cloud uses an OAuth-style device flow so you never paste a token by hand. The CLI requests a code, you approve it in the browser, and the CLI receives a token it stores at ~/.config/floom/credentials.json.

$ floom login --cloud

Under the hood:

1. CLI → POST /api/cli-auth/devices → { device_code, user_code, verification_url, polling_interval_seconds, expires_in_seconds }.
2. CLI prints user_code + opens verification_url; you confirm the code matches and approve in the browser.
3. CLI polls POST /auth/cli-exchange with { device_code, user_code } until it returns a token (honoring Retry-After on 429). The older GET /api/cli-auth/poll/… shape is self-hosted only.

Anti-phishing

Only approve a device code you started yourself, and verify the user_code on screen matches the one in your terminal before approving.

Session JWT

Browser sessions use a Supabase access token sent as Authorization: Bearer <jwt>. Access tokens last about an hour; the dashboard refreshes them via POST /auth/refresh using theworkeros_cloud_session cookie. (Cloud auth-overlay routes live under /auth, not /api;/auth/me is additionally aliased at /api/auth/me.) You generally only need this if you are building a web client that signs in users directly — for servers and scripts, use an API token instead.

request

curl https://workeros-api.floom.dev/auth/me \
  -H "Authorization: Bearer <supabase_access_token>"

Workspace scoping

Every request runs in the context of one workspace. Resolution order:

The x-workeros-workspace: <workspace_id> header, if present (and you are a member).
Otherwise the token’s / session’s default (active) workspace.

List the workspaces you belong to, then scope a call explicitly:

curl

# discover your workspaces
curl https://workeros-api.floom.dev/api/workspaces -H "x-floom-token: floom_xxx"

# target a specific one
curl https://workeros-api.floom.dev/api/workers \
  -H "x-floom-token: floom_xxx" \
  -H "x-workeros-workspace: ws_123"

With the CLI, switch the active workspace once and every later command inherits it: floom workspaces switch <name-or-id>. See the CLI reference.

Auth errors

401Unauthorized

Missing or invalid credential. Check the header name and that the token isn’t revoked/expired.

403Forbidden

Authenticated, but not a member of the target workspace or lacking permission for the resource.

429Too Many Requests

Rate limited. Honor the Retry-After header.

Errors return a JSON body of the shape { "detail": "<message>" }.