Skip to content
API referenceKeys

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

GET/v1/whoami

Which 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

appobjectrequired

The app the key belongs to.

Child attributes
idstringrequireduuid
namestringrequired
environmentstringrequired

sandbox for a test key (fg_test_…), production for a production key (fg_live_…).

One of production sandbox

keyIdstringrequired

The key id the request was signed with.

Errors

401missing_signature

One of x-fg-key, x-fg-timestamp and x-fg-signature is missing.

401invalid_timestamp

x-fg-timestamp is not Unix time in seconds.

401stale_timestamp

x-fg-timestamp is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.

401invalid_key

The key id is unknown or revoked, or the app is archived.

401invalid_signature

The signature does not match. Sign the exact bytes you send.

429too_many_attempts

Too many requests with this key in the last minute. Wait Retry-After seconds.

Request
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"
200 OK
{
  "app": {
    "id": "0c9e6f3a-1b2d-4c5e-8f7a-9b0c1d2e3f4a",
    "name": "Example Shop"
  },
  "environment": "sandbox",
  "keyId": "fg_test_k7qxa2mpw"
}

Check your setup

POST/v1/verify

Checks, 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 strings≤ 50 items

The event types your backend sends, up to 50. Each is checked against your app’s events and its payouts.

expectedEnvironmentstring

The environment this backend means to send to. A key for the other one fails the environment check.

One of production test

Returns · 200

okbooleanrequired

True when no check has the status fail.

appobjectrequired

The app the key belongs to.

Child attributes
idstringrequireduuid
namestringrequired
statusstringrequired

One of draft active archived

environmentstringrequired

test for a test key (fg_test_…), production for a production key (fg_live_…).

One of production test

keyIdstringrequired

The key id the request was signed with.

programobjectrequirednullable

The app’s program, or null when it has none.

Child attributes
idstringrequireduuid
namestringrequired
statusstringrequired

One of draft in_review active paused archived

serverTimestringrequireddate-time

Flow’s clock when it answered.

checksarray of objectsrequired
Child attributes
idstringrequired

Stable, 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

statusstringrequired

One of ok warn fail info

titlestringrequired

A short name for the check.

messagestringrequired

One sentence: what is right, or what to fix.

detailsany

Errors

400validation_error

The request does not match the schema. details says which fields failed and why.

401missing_signature

One of x-fg-key, x-fg-timestamp and x-fg-signature is missing.

401invalid_timestamp

x-fg-timestamp is not Unix time in seconds.

401stale_timestamp

x-fg-timestamp is more than 300 seconds from the server clock. Sign each attempt again, and keep your clock in sync.

401invalid_key

The key id is unknown or revoked, or the app is archived.

401invalid_signature

The signature does not match. Sign the exact bytes you send.

429too_many_attempts

More than 30 checks with this key in the last minute. Wait Retry-After seconds.

Request
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"
200 OK
{
  "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"
      }
    }
  ]
}