Keys and sign-in

Anyone, including an AI coding agent, can get a test key without an account. A person signs in later, with a Flow account (flow.engineer: Google, GitHub or an email link), to keep the app and get more room in the sandbox.

1. Get a key in one call

First check whether you already have one: if FLOW_MESSAGING_KEY is set (in the environment or .env), use it and skip this step.

curl

curl -X POST https://api.flow.engineer/v0/sandbox/keys
# Optional name, shown in the dashboard once the app is claimed:
# -H "Content-Type: application/json" -d '{"name": "Support agent"}'

CLI

npx @flow-engineer/messaging init

TypeScript

import { FlowMessaging } from "@flow-engineer/messaging";

const flow = new FlowMessaging(); // no key needed for this call
const sandbox = await flow.sandbox.createKey({ name: "Support agent" });
// save sandbox.key as FLOW_MESSAGING_KEY and sandbox.claim_token as FLOW_CLAIM_TOKEN

Example key response

The answer (201, a SandboxKey, shortened here) is a new app of its own:

{
  "key": "fk_test_...",
  "claim_token": "fct_...",
  "claim_url": "https://api.flow.engineer/admin/claim#token=fct_...",
  "api_key": { "id": "key_...", "mode": "test", "expires_at": "2026-10-17T09:30:00Z" },
  "app": { "id": "app_...", "name": "Sandbox app", "sandbox_join_code": "wild-otter-04508705" },
  "allowance": { "tier": "anonymous", "contacts": { "limit": 1, "used": 0 }, "messages": { "limit": 50, "used": 0, "remaining": 50 } },
  "senders": [
    { "id": "snd_...", "channel": "telegram", "kind": "shared", "address": { "link": "https://t.me/..." }, "join_code": "Hi Sandbox app (ref wild-otter-04508705)" }
  ]
}

• key and claim_token are shown once. Save key as FLOW_MESSAGING_KEY and claim_token as FLOW_CLAIM_TOKEN, in the environment or a git-ignored .env. The claim token (and claim_url, which holds it) lets a person claim the app, so treat it like the key.
• Join from a phone: open a sender’s address.link (on Telegram, tap Start), or send it the join_code (the whole message, as it is).
• Don’t call it again when you already have a key. Calls are limited per client address and network; going over answers 429 rate_limited with retry_after.

init does all of this: with no key in the environment or .env, it gets one itself, writes FLOW_MESSAGING_KEY and FLOW_CLAIM_TOKEN to .env, and prints the sandbox link and join code, the allowance and the expiry. To use a key you already have, pass init --key fk_test_....

2. The sandbox allowance

Test keys send only on Flow’s shared sandbox senders, and only to people who joined your app there. What an app may send there for free:

	No account (key from POST /v0/sandbox/keys)	Signed in (Flow account)
Contacts	1	3
Messages	50 in total	100 per contact
Channels	Telegram sandbox (WhatsApp when its sandbox opens)	Telegram sandbox (WhatsApp when its sandbox opens)
Key expiry	7 days (api_key.expires_at)	none

• Only messages your agent sends count. Inbound messages are free.
• A contact counts once it joins your app, and keeps counting after it leaves.
• iMessage is not part of either allowance. Flow’s shared iMessage line comes with the account’s free trial: your first sign-in at flow.engineer (the dashboard), or the first key you make there, starts it, and the Flow CLI’s npx @flow-engineer/flow setup starts the same trial. It has room for up to 25 people per channel, with test and live keys, and your own account’s apps use it instead of the signed-in allowance (see Pricing). Dedicated lines are arranged with the Flow team.
• The WhatsApp sandbox is not open yet; when it opens, the allowance covers it.
• When a key from POST /v0/sandbox/keys expires, its keys stop working and its contact is removed from the sandbox. A person can still sign in and claim the app.
• Going live: signed in, you make fk_live_ keys in the dashboard (Keys, Live) and connect your own Telegram bot or WhatsApp number; dedicated iMessage lines are arranged with the Flow team. See Going live.

See what is left with GET /v0/app (shortened):

curl https://api.flow.engineer/v0/app -H "Authorization: Bearer $FLOW_MESSAGING_KEY"

{
  "allowance": {
    "tier": "anonymous",
    "channels": ["telegram", "whatsapp"],
    "contacts": { "limit": 1, "used": 1 },
    "messages_per_contact": 50,
    "messages": { "limit": 50, "used": 12, "remaining": 38 },
    "expires_at": "2026-10-17T09:30:00Z",
    "upgrade": "Sign in to keep this app and send 100 messages to each of 3 contacts: npx @flow-engineer/messaging login"
  }
}

In TypeScript: (await flow.app.retrieve()).allowance.

3. Sign in to keep the app

Sign in with your Flow account to claim the app and keep its data. The signed-in allowance is shared across your apps: three contacts, 100 messages each, with up to ten claimed apps.

• CLI or device flow: the new key replaces the sandbox key, which stops working immediately.
• Browser claim: no new key is returned. The old key is revoked unless you select Keep my agent’s current key working.
• Kept keys: expiry is removed. An expired key can work again if the app is claimed within 30 days of expiry. For a revoked key, create a replacement in the dashboard.

With the CLI

npx @flow-engineer/messaging login

It reads FLOW_CLAIM_TOKEN from .env, prints a link and a short code (for example WDJB-MJHT), opens the browser and waits. Once the person approves, it replaces FLOW_MESSAGING_KEY in .env with the new key and removes FLOW_CLAIM_TOKEN. --no-browser skips opening the browser.

Coding agents that cannot wait on a command: run npx @flow-engineer/messaging login --no-wait. It prints the link and code and exits. Show them to the person, and once they say they approved, run npx @flow-engineer/messaging login again to collect the key.

With curl

1. Start the sign-in with the claim token. client_name is shown to the person on the approval page.

   curl -X POST https://api.flow.engineer/v0/device/authorizations \
     -H "Content-Type: application/json" \
     -d '{"claim_token": "'"$FLOW_CLAIM_TOKEN"'", "client_name": "Claude Code"}'

   {
     "device_code": "fdc_...",
     "user_code": "WDJB-MJHT",
     "verification_uri": "https://api.flow.engineer/admin/device",
     "verification_uri_complete": "https://api.flow.engineer/admin/device?code=WDJB-MJHT",
     "expires_in": 900,
     "interval": 5
   }

   Without a claim token, send the app’s test key instead (-H "Authorization: Bearer $FLOW_MESSAGING_KEY").

2. Show the person verification_uri and user_code: they open the page, sign in and type the code you show them (a link alone never approves; verification_uri_complete opens the same page). Never show device_code.

3. Poll every interval seconds:

   curl -X POST https://api.flow.engineer/v0/device/token \
     -H "Content-Type: application/json" -d '{"device_code": "fdc_..."}'

   • pending: wait interval seconds and poll again. 429 rate_limited means slow down: wait retry_after seconds.
   • approved: the answer holds key (shown once). Save it as FLOW_MESSAGING_KEY in place of the sandbox key, and drop FLOW_CLAIM_TOKEN.
   • denied: the person refused. Stop.
   • expired: the codes ran out (after 15 minutes) or were already used. Start again.

With TypeScript

import { DeviceSignInError, FlowMessaging } from "@flow-engineer/messaging";

const flow = new FlowMessaging();
try {
  const token = await flow.device.signIn({
    claimToken: process.env.FLOW_CLAIM_TOKEN,
    clientName: "My agent",
    prompt: (auth) => console.log(`Open ${auth.verification_uri_complete} and check the code ${auth.user_code}`),
  });
  // token.key replaces FLOW_MESSAGING_KEY
} catch (err) {
  if (err instanceof DeviceSignInError) console.log(`Sign-in ${err.reason}`); // "denied" or "expired"
  else throw err;
}

signIn polls for you, honouring interval and retry_after. For your own loop, use flow.device.authorize({ claimToken, clientName }) and flow.device.poll(deviceCode).

In a browser

claim_url opens a page where the person signs in and claims the app without the CLI.

The dashboard

Dashboard and account linking

Signed-in people manage their apps and keys at api.flow.engineer/admin (sign in with a Flow account), including creating and revoking test and live keys. A Flow account is the one you use on flow.engineer: sign in there with Google, GitHub or an email link. flow.engineer/login is the only sign-in page: the dashboard and the device flow send you there and bring you back, at once when you are already signed in on flow.engineer. If you used the dashboard with GitHub before Flow accounts, sign in once on flow.engineer with the same email and ask the Flow team to link the two, so you keep your apps and keys; accounts are never linked by email on their own.

Errors

Allowance and sign-in errors

Error	channel_code	What it means	What to do
403 permission	sandbox_allowance_used	The app sent all the messages its allowance allows.	Sign in (login) for 100 per contact for 3 contacts, shared by all your apps. Signed in already: go live.
403 permission	sandbox_contact_limit	The allowance has no room for another contact.	Sign in for 3 contacts, or keep testing with the contact who joined.
403 permission	sandbox_channel_not_included	The send used a sandbox channel the allowance does not cover, such as iMessage.	Use the Telegram sandbox sender. For the shared iMessage line, sign in at flow.engineer to start the free trial (or run npx @flow-engineer/flow setup).
403 permission	sign_in_required	An app made without an account tried something that needs a person signed in, such as connecting its own Telegram bot.	Sign in (login), then retry.
401 authentication	sandbox_key_expired	The key from POST /v0/sandbox/keys is past its expires_at (7 days).	Sign in to claim the app within 30 days of the expiry (the key works again, and you get a new one), or get a new key with POST /v0/sandbox/keys.

Switch on error.type and read error.channel_code; each error also carries a hint and a doc_url (permission, authentication, rate_limited).