API reference · App API
Keys
Check which app and environment a key belongs to, and whether your setup is ready, before you send anything with it.
Check a key
/v1/whoamiWhich app and environment the key you signed with belongs to. Nothing is stored, so it is the request to test a connection with: a 401 says whether the key, the secret or the clock is wrong.
AuthSigned request with an app key, fg_live_… or fg_test_…
Returns · 200
appobjectrequiredThe app the key belongs to.
Child attributes
idstringrequirednamestringrequiredenvironmentstringrequiredsandbox for a test key (fg_test_…), production for a production key (fg_live_…).
One of production sandbox
keyIdstringrequiredThe key id the request was signed with.
Errors
- 401
missing_signature One of
x-fg-key,x-fg-timestampandx-fg-signatureis missing.- 401
invalid_timestamp x-fg-timestampis not Unix time in seconds.- 401
stale_timestamp x-fg-timestampis more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.- 401
invalid_key The key id is unknown or revoked, or the app is archived.
- 401
invalid_signature The signature does not match. Sign the exact bytes you send.
- 429
too_many_attempts Too many requests with this key in the last minute. Wait
Retry-Afterseconds.
TS=$(date +%s)
SIG=$(printf '%s.' "$TS" | openssl dgst -sha256 -hmac "$FG_SECRET" | sed 's/^.*= //')
curl "https://api.sqaler.io/v1/whoami" \
-H "x-fg-key: $FG_KEY_ID" \
-H "x-fg-timestamp: $TS" \
-H "x-fg-signature: $SIG"import { createFlowGrowth } from '@flow/growth-sdk';
const fg = createFlowGrowth({
baseUrl: 'https://api.sqaler.io',
keyId: process.env.FG_KEY_ID!, // fg_test_… in the sandbox
secret: process.env.FG_SECRET!,
});
const res = await fg.whoami();
if (res.ok) console.log(res.data.app.name, res.data.environment); // 'sandbox' for a fg_test_ key{
"app": {
"id": "0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a",
"name": "Example Shop"
},
"environment": "sandbox",
"keyId": "fg_test_k7qxa2mpw"
}Check your setup
/v1/verifyChecks, in one signed request, whether your backend is set up right: the key, its environment, your clock, the app and its program, the event types you send and which of them pay publishers, the store links, refused signatures and the last event received. Nothing is stored, so it is safe to call from a "Test connection" button with a production key.
Send {} for the checks that need nothing from you, and add events and expectedEnvironment for the rest. A wrong key, secret or clock is still a 401, as on every signed request.
AuthSigned request with an app key, fg_live_… or fg_test_…
Request body
eventsarray of stringsThe event types your backend sends, up to 50. Each is checked against your app’s events and its payouts.
expectedEnvironmentstringThe environment this backend means to send to. A key for the other one fails the environment check.
One of production test
Returns · 200
okbooleanrequiredTrue when no check has the status fail.
appobjectrequiredThe app the key belongs to.
Child attributes
idstringrequirednamestringrequiredstatusstringrequiredOne of draft active archived
environmentstringrequiredtest for a test key (fg_test_…), production for a production key (fg_live_…).
One of production test
keyIdstringrequiredThe key id the request was signed with.
programobjectrequiredThe app’s program, or null when it has none.
Child attributes
idstringrequirednamestringrequiredstatusstringrequiredOne of draft in_review active paused archived
serverTimestringrequiredFlow’s clock when it answered.
checksarray of objectsrequiredChild attributes
idstringrequiredStable, in this order: - key: the key and secret are right (always ok: a wrong one is a 401). - clock: your clock is within 60 seconds of Flow’s; details.skewSeconds is positive when yours is ahead. - environment: only with expectedEnvironment; fail when the key is for the other one. - app: whether the app is active or still a draft. - program: fail without a program, warn until it is live; details.openSteps lists its setup steps still open. - events: only with events; fail when some are not in your app’s events (details.missing). - payouts: which event types pay publishers (details.paysOn, paying, notSent); warn when none you send does. - store_links: warn when an app has no App Store or Google Play link. - signature_failures: requests with this app and environment refused for a wrong signature in the last day (details.count). - last_event: the last event received in this environment, if any (details.type, status, receivedAt).
One of key clock environment app program events payouts store_links signature_failures last_event
statusstringrequiredOne of ok warn fail info
titlestringrequiredA short name for the check.
messagestringrequiredOne sentence: what is right, or what to fix.
detailsanyErrors
- 400
validation_error The request does not match the schema.
detailssays which fields failed and why.- 401
missing_signature One of
x-fg-key,x-fg-timestampandx-fg-signatureis missing.- 401
invalid_timestamp x-fg-timestampis not Unix time in seconds.- 401
stale_timestamp x-fg-timestampis more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.- 401
invalid_key The key id is unknown or revoked, or the app is archived.
- 401
invalid_signature The signature does not match. Sign the exact bytes you send.
- 429
too_many_attempts More than 30 checks with this key in the last minute. Wait
Retry-Afterseconds.
BODY='{"events":["user.registered","purchase.completed"],"expectedEnvironment":"production"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$FG_SECRET" | sed 's/^.*= //')
curl -X POST "https://api.sqaler.io/v1/verify" \
-H "content-type: application/json" \
-H "x-fg-key: $FG_KEY_ID" \
-H "x-fg-timestamp: $TS" \
-H "x-fg-signature: $SIG" \
--data-raw "$BODY"import { createHmac } from 'node:crypto';
const body = JSON.stringify({
events: [
'user.registered',
'purchase.completed'
],
expectedEnvironment: 'production'
});
const ts = Math.floor(Date.now() / 1000);
const signature = createHmac('sha256', process.env.FG_SECRET!).update(`${ts}.${body}`).digest('hex');
const res = await fetch('https://api.sqaler.io/v1/verify', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-fg-key': process.env.FG_KEY_ID!,
'x-fg-timestamp': String(ts),
'x-fg-signature': signature,
},
body,
});{
"ok": true,
"app": {
"id": "0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a",
"name": "Example Shop",
"status": "active"
},
"environment": "production",
"keyId": "fg_live_k7qxa2mpw",
"program": {
"id": "5d2e8a1c-4b3f-4e6d-9a7b-1c2d3e4f5a6b",
"name": "Example Shop",
"status": "active"
},
"serverTime": "2026-11-13T10:00:00.000Z",
"checks": [
{
"id": "key",
"status": "ok",
"title": "Key and secret",
"message": "Key fg_live_k7qxa2mpw belongs to Example Shop, production."
},
{
"id": "clock",
"status": "ok",
"title": "Clock",
"message": "Your server’s clock is within 60 seconds of Flow’s.",
"details": {
"skewSeconds": 1
}
},
{
"id": "environment",
"status": "ok",
"title": "Environment",
"message": "This is a production key, as expected."
},
{
"id": "app",
"status": "ok",
"title": "App",
"message": "Example Shop is active."
},
{
"id": "program",
"status": "ok",
"title": "Program",
"message": "Example Shop is live: publishers can join and events pay.",
"details": {
"openSteps": []
}
},
{
"id": "events",
"status": "ok",
"title": "Event types",
"message": "Every event type you send is in Example Shop’s events."
},
{
"id": "payouts",
"status": "info",
"title": "Payouts",
"message": "Of the types you send, purchase.completed pays publishers.",
"details": {
"paysOn": [
"purchase.completed"
],
"paying": [
"purchase.completed"
],
"notSent": []
}
},
{
"id": "store_links",
"status": "info",
"title": "Store links",
"message": "Example Shop is a website, so its links need no store link."
},
{
"id": "signature_failures",
"status": "ok",
"title": "Refused signatures",
"message": "No request with a production key was refused for a wrong signature in the last day.",
"details": {
"count": 0
}
},
{
"id": "last_event",
"status": "info",
"title": "Last event",
"message": "The last production event Flow received was purchase.completed, at 2026-11-13T09:58:12.000Z.",
"details": {
"type": "purchase.completed",
"status": "processed",
"receivedAt": "2026-11-13T09:58:12.000Z"
}
}
]
}