Authentication

The Flowy API authenticates with API keys (created in the dashboard) or OAuth access tokens (minted when you connect an AI agent; see the MCP server). Send either as a Bearer token in the Authorization header on every request:

Authorization: Bearer flowy_xxxxxxxx

A missing, malformed, revoked, or expired credential returns 401 Unauthorized. Who pays: OAuth connections are account-bound: by default they act in and bill your personal account wallet, and can act in any workspace you can manage by passing workspace_id (see List workspaces). Dashboard API keys belong to the workspace they were created in and bill that workspace by default.

Secret vs publishable keys

Publishable keys are coming soon. Today every key you create is a secret key: the publishable column below previews what’s next.

There are two kinds of key. Pick the one that matches where your code runs.

	Secret key	Publishable key
Prefix	`flowy_…`	`flowy_pk_…`
Use it	Server-side only	In a browser / client app
Protected by	Keeping it private	A per-key domain allowlist

A secret key grants full use of its scopes to anyone who has it. Treat it like a password and keep it server-side. A publishable key is meant to be visible in client code, so its only real protection is the domain allowlist (plus its scopes, daily cap, and rate limit). Give publishable keys the narrowest scopes and a sensible spend cap.

Create a key

Open API keys settings

In the app, go to Settings → API keys. You’ll need to be a workspace owner or editor.

Choose the key's shape

Pick an owner (You or Machine) and a permission level (All, Read-only, or Restricted). Optionally set a daily spend cap and rate limit under advanced options.

Copy it now

Your key (flowy_…) is shown once. Copy it and store it in a secrets manager or server environment variable. You won’t be able to see it again.

Key owner: You vs Machine

When you create a key you choose who owns it:

You: the key is tied to your user account.
Machine: the key is owned by a workspace service account. It keeps working even if you later leave the workspace, and runs are attributed to the service account rather than to you. The service account takes no seat and never appears in your members list.

Use a Machine owner for long-lived production integrations, so the key doesn’t break the day the person who created it changes teams.

Authenticate a request

export FLOWY_API="https://apis.tryflowy.ai/genstudio-svc-v2/api/v1"
export FLOWY_KEY="flowy_..."

curl "$FLOWY_API/apps" \
  -H "Authorization: Bearer $FLOWY_KEY"

const BASE = "https://apis.tryflowy.ai/genstudio-svc-v2/api/v1";
const KEY = process.env.FLOWY_KEY; // "flowy_..."

const res = await fetch(`${BASE}/apps`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();

import os, requests

BASE = "https://apis.tryflowy.ai/genstudio-svc-v2/api/v1"
KEY = os.environ["FLOWY_KEY"]  # "flowy_..."

res = requests.get(f"{BASE}/apps", headers={"Authorization": f"Bearer {KEY}"})
data = res.json()["data"]

Every request you make with a key is recorded in Settings → Logs: useful for debugging your integration and auditing what a key has been doing.

Using a publishable key in the browser

Publishable keys aren’t available to create yet. This section previews how they’ll work.

A publishable key works the same way, Authorization: Bearer flowy_pk_…, but the request must come from one of the key’s allowed domains (matched on the Origin, falling back to the Referer). Add example.com for an exact host, or *.example.com to allow any subdomain. A request from a domain that isn’t allowlisted returns 403 Forbidden.

Browser

// Runs from https://example.com — an allowed domain — succeed.
await fetch(`${BASE}/apps/${appId}/runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${PUBLISHABLE_KEY}`, // flowy_pk_...
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ inputs: [{ node_id: "scene", prompt: "a red bicycle" }] }),
});

Protecting your keys

Because a leaked key spends your workspace credits, every key has several safeguards. Set them when you create or edit a key:

Safeguard	What it does
Scopes	Limit which operations the key can perform: e.g. a read-only key can’t start runs. See Permissions.
Domain allowlist	For publishable keys: only requests from your domains are accepted.
Daily spend cap	Once the key spends its cap (credits/day), new runs are rejected with `402` until the next UTC day.
Rate limit	Caps requests per minute for the key. Excess requests get `429`. See Rate limits.
Revoke	Disables the key immediately. The Last used column and the request logs help you spot a key behaving unexpectedly.

Your workspace’s available credit balance is always the final backstop: when it reaches zero, runs stop regardless of any cap.

Get started

Endpoints

Reference

Authentication

Secret vs publishable keys

Create a key

Key owner: You vs Machine

Authenticate a request

Using a publishable key in the browser

Protecting your keys

​Secret vs publishable keys

​Create a key

​Key owner: You vs Machine

​Authenticate a request

​Using a publishable key in the browser

​Protecting your keys

Secret vs publishable keys

Create a key

Key owner: You vs Machine

Authenticate a request

Using a publishable key in the browser

Protecting your keys