Keys and sign-in

​

1. Get a key in one call

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"}'

npx @flow-engineer/messaging init

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

{
  "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.

​

2. The sandbox allowance

• 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.

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"
  }
}

​

3. Sign in to keep the app

• 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

​

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;
}

​

In a browser

​

The dashboard

​

Errors