Developers: integrate FingerPrint Checker in web, iOS and Android apps

Tag an identify with your own ids

An identify request may carry two optional fields. linkedId is your own user, order or session id (1 to 256 characters, no control characters). tags is a JSON object of your own labels (up to 4 KiB serialised, at most 3 levels deep). Invalid values are rejected with invalid_linked_id or invalid_tags before anything is stored.

Every successful identify now returns an eventId. You can set or change linkedId, tags and suspect on that event later with PATCH /v1/events/{eventId}, and then search by linkedId.

// Server side, secret key. Only linkedId, tags and suspect can be changed.
if (!/^ev_[0-9A-HJKMNP-TV-Z]{20}$/.test(eventId)) throw new Error('bad eventId'); // fail closed
await fetch(`https://api.fpchecker.com/v1/events/${eventId}`, {
  method: 'PATCH',
  headers: { 'content-type': 'application/json', 'X-Secret-Key': process.env.FPCHECKER_SECRET_KEY },
  body: JSON.stringify({ linkedId: 'user_123', tags: { page: 'checkout' }, suspect: false }),
});

Events API

Each identify is stored as an event for the retention period you choose in the console (7 to 90 days). Read events with your secret key; the calls are free and rate limited. An id that does not exist or belongs to another project answers 404.

GET /v1/events filters: visitorId, linkedId, ip (one address, or a range no wider than /16 for IPv4 or /48 for IPv6), suspect, bot, vpn, proxy, tor, incognito, tampering, virtualMachine, rooted, hooked, emulator, mitm, locationSpoofed and clonedApp (each true or false; see Signals below), platform (web, android, ios, macos or cli), start and end (ISO times; the default is the last 7 days and the span cannot exceed your retention), limit (1 to 100, default 20) and cursor. The answer is { events, next }; pass next as cursor for the following page.

GET /v1/visitors/{visitorId} returns first and last seen, the number of events, up to 20 recent linkedIds and up to 20 recent events. DELETE /v1/visitors/{visitorId} erases this project’s events and device records for the visitor (for privacy requests); it is idempotent and does not touch other projects.

Events are also listed in the console, where you can open one, see its raw JSON and export up to 1,000 rows as CSV.

// Every event, newest first. Fails closed: an error is never read as "no events".
let cursor;
do {
  const url = new URL('https://api.fpchecker.com/v1/events');
  url.searchParams.set('linkedId', 'user_123');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const r = await (await fetch(url, { headers: { 'X-Secret-Key': process.env.FPCHECKER_SECRET_KEY } })).json();
  if (!r.events) throw new Error(r.error ?? r.reason);
  for (const event of r.events) handle(event); // your code
  cursor = r.next;
} while (cursor);

// One event: {
//   v: 1, eventId, projectId, visitorId, createdAt, platform, protocol, isNew,
//   identityConfidence, trustScore, linkedId, tags, suspect, ip,
//   ipInfo: { asn, country, timezone }, origin, agentVersion,
//   signals: { version: 2, ... } | null   (see Signals; older events read as version 1)
// }

Signals

Every event carries a signals object (version 2 on events stored since the bot directory release, version 1 on older ones; the only difference is the bot field) with what the server learned about the visit. It is on the events API, in the console and in webhooks, and never in the answer the browser or app receives. The signals are evidence to weigh, not verdicts, and they do not change the decision or trustScore.

Unknown is null, not false. false means the check ran and found nothing; null means it could not run (no data for that IP, a field the platform does not have, a source that is down). vpn.result: null is not “no VPN”. An event stored before signals existed has signals: null, and a webhook queued before the release may omit the key; treat missing and null alike.

Fields: ip (country, city, timezone, asn, asName, datacenter, tor, relay, blocklist); vpn (result and methods: timezone_mismatch, ip_range, relay, os_vpn; os_vpn comes from the mobile SDKs and means a device-level VPN, and consumers should ignore methods they do not know; timezone_mismatch also fires for a traveller whose device clock differs from the IP’s zone, and relay alone does not make result true); proxy (result, type datacenter); bot (result good, bad or not_detected, types webdriver, headless, playwright, selenium, inhuman_timing, inconsistent_environment, and on version 2 an info object { id, name, provider, category, identity } that is null when the visit matched no directory entry; identity is verified, signed, unknown or spoofed, see Bot check below; version 1 events never have good or info, and consumers should ignore values they do not know); tampering (result, antiDetectBrowser); privacyBrowser (result, name brave, firefox_rfp or tor_browser; not a risk by itself); virtualMachine; velocity; and mobile (see Mobile signals below; Android, iOS and macOS only, null for web).

velocity counts distinct IPs, countries and linkedIds, and events, for this visitor in the last 5 minutes, 1 hour and 24 hours including this event. It is approximate, and the whole object is null when the database was slow or busy. ip.blocklist.result is null when the list is unavailable or out of date, or the IP is IPv6 and the list has no IPv6 entries.

incognito reports private browsing in Chrome and Firefox on desktop: true or false there, null in every other browser and in native apps, and null whenever it cannot be told. It is not part of the trust score. devtools is reserved and always null: no release reports open developer tools. On native events bot and privacyBrowser keep their shape with result null, and virtualMachine is null. On native events tampering.result reflects device tampering (rooted or jailbroken, or hooked), and antiDetectBrowser stays null.

Search filters on GET /v1/events, each true or false: bot, vpn, proxy, tor, incognito, tampering, virtualMachine, rooted, hooked, emulator, mitm, locationSpoofed and clonedApp. The console form offers all of them. incognito=true and incognito=false match Chrome and Firefox desktop events only; every other event has null. bot=true matches bot.result bad (good does not count) and bot=false matches not_detected; the version 2 filters bot_result (good, bad or not_detected), bot_category, bot_identity (verified, signed, unknown or spoofed) and bot_id (a directory id) match only version 2 events; tor matches ip.tor; an unknown (null) value matches neither true nor false. Any other value is 400 invalid_request.

IP data attribution: wherever your product shows asName, show “IP address data powered by IPinfo” next to it.

// event.signals (null for events stored before signals existed)
{
  version: 2,
  ip: {
    country: 'DE', city: 'Berlin', timezone: 'Europe/Berlin', asn: 64500, asName: 'Example Hosting GmbH',
    datacenter: true, tor: false, relay: false, blocklist: { result: false, sources: [] },
  },
  vpn: { result: true, methods: ['timezone_mismatch'] },
  proxy: { result: true, type: 'datacenter' },
  bot: { result: 'bad', types: ['headless'], info: null },
  incognito: false,
  tampering: { result: false, antiDetectBrowser: false },
  privacyBrowser: { result: false, name: null },
  virtualMachine: false,
  devtools: null,
  velocity: {
    distinctIp: { '5m': 1, '1h': 2, '24h': 3 },
    distinctCountry: { '5m': 1, '1h': 1, '24h': 2 },
    distinctLinkedId: { '5m': 1, '1h': 1, '24h': 1 },
    events: { '5m': 2, '1h': 4, '24h': 9 },
  },
  mobile: null,
}

Request filtering

A project can refuse unwanted traffic before anything is billed or recorded. The filters run on the four routes a browser or app talks to (challenge and identify, v1 and v2), and you set them per project in the console. A change takes effect within a minute.

Allowed origins: when the list is not empty, a request that carries an Origin header outside the list is refused. A request with no Origin header passes, as native apps and server callers send none. IP deny list: addresses and CIDR ranges, IPv4 and IPv6, up to 100 entries. Header rules: up to 20 rules, any one match refuses; each is a header name with equals, contains or exists and a value. Block crawlers: off by default; refuses requests from search engine and AI crawlers that announce themselves.

A refused request gets HTTP 403 with { "ok": false, "error": "request_filtered" }. The body never says which filter matched. It is not billed, writes no event and does not count against your write budget. Treat it like project_disabled: do not retry, and do not show it as a failed check of the visitor. A page that suddenly gets it from its own origin usually has that origin missing from the allowed list.

The console shows, for the last 7 days, how many requests each filter refused.

const r = await fetch('https://api.fpchecker.com/v2/identify', { method: 'POST', /* ... */ });
if (r.status === 403) {
  const body = await r.json();
  if (body.error === 'request_filtered') {
    // Refused by your own filters. Do not retry.
  }
}

Bot check

POST /v1/bot-check classifies a plain HTTP request that reached your backend, without the browser script. Send the method, the full URL, the client IP and the request headers with your secret key (sk_…). We never fetch the URL. The call is free, writes no event and is limited to 1,200 a minute per project and 3,000 a minute per calling IP (your server’s address); over either limit it answers 429.

Limits: the body is at most 32 KiB, with at most 64 headers of at most 4,096 characters each, and the url is at most 2,048 characters. Header names are lower-cased.

Answer: bot.result is good, bad or not_detected. bot.info names the directory entry (id, name, provider, category, identity) and is null when the request matched none. identity is verified, signed, unknown or spoofed; good needs verified or signed. Without the browser script the only bot.types are automation_tool (an HTTP library rather than a browser), headless and missing_headers (a browser that lacks headers every real browser sends). ip and proxy carry the network facts known for the address, and vpn carries only the network-based result and methods. There are no tampering, incognito or device fields.

Forward only these headers: user-agent, accept, accept-language, accept-encoding, sec-ch-ua, sec-ch-ua-mobile, sec-ch-ua-platform, sec-fetch-site, sec-fetch-mode, sec-fetch-dest, sec-fetch-user, signature, signature-input, signature-agent, upgrade-insecure-requests. Also forward every header named in the request’s signature-input (its covered components that do not start with @), because a signature fails when a covered header is missing. Still never forward cookie or authorization. Send the client IP your platform has verified, not one the client can choose.

Signed agents: some agents sign their requests with Web Bot Auth, a public standard for signed bot requests. When the operator is listed in the bot directory as Signed, forward signature, signature-input and signature-agent unchanged and send the url exactly as the agent requested it; a valid signature is confirmed as a good bot, and a failed one as spoofed. A request signed by an operator that is not listed is judged by its other headers, as if unsigned. Call bot-check once per request and reuse the answer. Never retry a signed request: a replayed signature reads as spoofed.

Events carry the same result in signals.bot, and the events API searches it with bot_result (good, bad or not_detected), bot_category, bot_identity (verified, signed, unknown or spoofed) and bot_id (a directory id). bot=true still means a bad bot only.

// POST https://api.fpchecker.com/v1/bot-check   X-Secret-Key: sk_...
// request
{
  "method": "GET",
  "url": "https://shop.example.com/checkout?x=1",
  "ip": "203.0.113.9",
  "headers": { "user-agent": "curl/8.5.0", "accept": "*/*" }
}
// response
{
  "bot": { "result": "bad", "types": ["automation_tool"], "info": null },
  "ip": { "country": "US", "asn": 16509, "asName": "Amazon.com, Inc.", "datacenter": true, "tor": false, "relay": false, "blocklist": { "result": false, "sources": [] } },
  "vpn": { "result": null, "methods": [] },
  "proxy": { "result": true, "type": "datacenter" }
}

Express middleware

Forwards the allowed headers plus the ones the signature covers. Call it once per request and keep the answer; never retry a signed request. If the call fails, let the request through or fall back to your own policy; do not treat an error as a bad bot.

const FORWARD = ['user-agent', 'accept', 'accept-language', 'accept-encoding', 'sec-ch-ua', 'sec-ch-ua-mobile', 'sec-ch-ua-platform', 'sec-fetch-site', 'sec-fetch-mode', 'sec-fetch-dest', 'sec-fetch-user', 'signature', 'signature-input', 'signature-agent', 'upgrade-insecure-requests'];
// Header names covered by signature-input, e.g. sig1=("@authority" "signature-agent");created=...
const covered = value => [...String(value ?? '').matchAll(/\(([^)]*)\)/g)]
  .flatMap(m => [...m[1].matchAll(/"([^"]*)"/g)].map(x => x[1].toLowerCase()))
  .filter(name => name && !name.startsWith('@') && !/^(?:cookie|authorization)$/.test(name));

// req.ip is only the real client when Express trusts your proxy: set a hop count or CIDR, never true.
app.set('trust proxy', 1);

app.use(async (req, res, next) => {
  const names = new Set([...FORWARD, ...covered(req.headers['signature-input'])]);
  const headers = Object.fromEntries([...names].filter(h => req.headers[h]).map(h => [h, String(req.headers[h])]));
  const r = await fetch('https://api.fpchecker.com/v1/bot-check', {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'X-Secret-Key': process.env.FPCHECKER_SECRET_KEY },
    body: JSON.stringify({ method: req.method, url: `https://${req.headers.host}${req.originalUrl}`, ip: req.ip, headers }),
  }).catch(() => null);
  const check = r?.ok ? await r.json() : null;
  if (check?.bot.result === 'bad') return res.status(403).end(); // your policy
  next();
});

Next.js middleware

The same call from middleware.ts. Take the client address from the header your ingress overwrites, never from one the client can choose.

import { NextResponse } from 'next/server';

const FORWARD = ['user-agent', 'accept', 'accept-language', 'accept-encoding', 'sec-ch-ua', 'sec-ch-ua-mobile', 'sec-ch-ua-platform', 'sec-fetch-site', 'sec-fetch-mode', 'sec-fetch-dest', 'sec-fetch-user', 'signature', 'signature-input', 'signature-agent', 'upgrade-insecure-requests'];
// Header names covered by signature-input, e.g. sig1=("@authority" "signature-agent");created=...
const covered = value => [...String(value ?? '').matchAll(/\(([^)]*)\)/g)]
  .flatMap(m => [...m[1].matchAll(/"([^"]*)"/g)].map(x => x[1].toLowerCase()))
  .filter(name => name && !name.startsWith('@') && !/^(?:cookie|authorization)$/.test(name));

export async function middleware(request) {
  // The header your ingress overwrites. Never use the leftmost X-Forwarded-For: the client controls it.
  const ip = request.headers.get('cf-connecting-ip');
  const names = new Set([...FORWARD, ...covered(request.headers.get('signature-input'))]);
  const headers = Object.fromEntries([...names].flatMap(h => (request.headers.get(h) ? [[h, request.headers.get(h)]] : [])));
  const r = await fetch('https://api.fpchecker.com/v1/bot-check', {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'X-Secret-Key': process.env.FPCHECKER_SECRET_KEY },
    body: JSON.stringify({ method: request.method, url: request.url, ip, headers }),
  }).catch(() => null);
  const check = r?.ok ? await r.json() : null;
  if (check?.bot.result === 'bad') return new NextResponse(null, { status: 403 }); // your policy
  return NextResponse.next();
}

Rules and ruleAction

Rules turn what the server learned about a visit into a decision your project applies, without code on your side. A project has one ruleset: an on/off switch and an ordered list of up to 50 rules, edited in the console. A rule has a name, an enabled flag, match all or any, up to 10 conditions and one action: allow, human_check or deny. The first enabled rule that matches decides.

A condition is { field, op, value }. Fields cover the signals (vpn, proxy, tor, blocklisted, tampered, virtualMachine, privacyBrowser, incognito, bot, botResult, botCategory, botIdentity, botId, botTypes), the mobile signals (rooted, hooked, emulator, debugger, developerMode, mitm, locationSpoofed, clonedApp), ipKind (hosting, vpn, relay, tor, mobile or other), country, asn, velocityIps1h, velocityCountries24h, velocityLinkedIds24h, trustScore, identityConfidence, isNew, platform, linkedId and tag.<key>. incognito is true or false for a Chrome or Firefox desktop private window and null everywhere else, so a condition on it is false there. bot is true only for a bad bot; botId must be an id from the bot directory. A condition on a value the server does not have is false, including neq and not_in, so a rule never fires on a guess. The console always offers the current field list.

In /v1/eligibility, deny answers eligible: false with reason rule_deny and the ruleId. human_check requires the human check for the request. allow skips only the first-claim network and trust checks (in a shared-device class the human check still runs) and answers rule_allow with the ruleId; it cannot override claim limits: it never skips the device, email, household or domain limits, so a rule cannot hand one device a second trial. In /v1/quota, only deny applies. Treat rule_deny and rule_allow like any other reason, and keep tolerating reasons you do not know.

Every event of a project with the ruleset on carries ruleAction, in the events API and in the webhook body: { type, ruleId, ruleName, rulesetVersion }. type is allow, human_check, deny or none when no rule matched; ruleAction is null when the ruleset is off. It is never in the answer the browser or app receives, so the visitor does not learn which rule caught them.

Rules are evaluated when the device is identified, so a change applies to identifications made after you save it. Before switching rules on, run an unsaved list against a stored event in the console: it shows which rule would decide and which others also match, and saves nothing.

// event.ruleAction on GET /v1/events and in webhooks
{ type: 'deny', ruleId: 'r_k3x9a1bc', ruleName: 'Deny Tor', rulesetVersion: 3 }

// POST /v1/eligibility when a rule refused the claim
{ eligible: false, action: 'deny', reason: 'rule_deny', ruleId: 'r_k3x9a1bc' }

Cloudflare proxy integration

You can serve the agent and the identify calls from your own domain with a small open-source Cloudflare Worker that you deploy in your own Cloudflare account. The Worker answers on yoursite.com/<path>/* (the default path is fpc) and forwards the challenge and identify routes, plus agent.js. Every other path is a 404. Its source and deploy steps are in integrations/cloudflare-worker of the open-source repository.

Create a proxy secret in the console (project, Cloudflare proxy). It is shown once; store it in the Worker as FPC_PROXY_SECRET. To use a path other than fpc, set FPC_PATH in the Worker; the route and the agent’s endpoint and scriptUrl must use the same path. A project has an active and a previous secret and accepts both, so you can rotate without downtime; delete the previous one when the Worker has the new value. Changes reach every server within about a minute.

The Worker adds X-FPC-Proxy-Secret and the visitor details (X-FPC-Client-IP, Country, Timezone, City, ASN and X-FPC-Forwarded-Host), and removes any X-FPC header a browser sent. Our servers use those details only from a caller with a valid secret, and then for the whole request: filters, rate limits, the event and its signals. Events report proxied: true. Without a secret the headers are ignored; a wrong secret answers 403 request_filtered, not billed. A valid secret without a visitor IP is refused.

Rate limiting: all proxied traffic arrives from the Worker’s egress addresses, so those get a loose circuit breaker first; once the secret verifies, per-visitor limits apply to the forwarded IP.

import { load } from '@fingerprintchecker/agent';

const fp = await load({
  endpoint: 'https://yoursite.com/fpc',
  scriptUrl: 'https://yoursite.com/fpc/agent.js',
});

Sealed results

A copy of eventId or visitorId that travelled through the browser or app can be edited on the way. With sealed results on, a successful identify answer (web v2 and the native SDKs) also carries sealedResult: a small encrypted record that only FingerPrint Checker could have produced and only your backend can read. Opening it proves the answer came from us for this project and gives you the event it recorded, without another API call. It is part of identify and adds no charge.

What is inside: eventId, visitorId, projectId (check that it is yours), linkedId, tags, timestamp (Unix milliseconds), platform and proofStatus, plus a version number. It has no signals, no score, no decision and no IP address: read signals from the events API, and get the decision from eligibility.

To turn it on, open the project in the console and use Sealing keys. Creating a key shows its value once; afterwards the console shows only the key id and the creation time, so store it in your backend’s secret store at once. Sealing starts straight away. Deleting the active key turns sealing off again.

Rotation uses two keys, active and previous. Rotating makes a new key active and the old active key previous. Put the new key into your backend next to the old one, and pass both to the unseal call: blobs sealed with either keep opening. Delete previous only after the last blob sealed with it has been used. A deleted key can still seal for up to 60 seconds on another server process.

A sealed result proves origin, not entitlement: it is not a grant. Grant a trial, coupon or credit only through the eligibility call with a fresh attestation. Before you use a sealed result for anything else, check projectId is yours, reject a timestamp older than about 5 minutes, and treat eventId as single-use (remember the ones you have seen), or match its linkedId to the signed-in user.

Be ready for a missing sealedResult: sealing is best effort, and an identify can succeed without one. Fall back to what you already trust, such as GET /v1/events/{eventId} with your secret key or the visitorId in the eligibility answer. Treat a failure to open a blob as “not from FingerPrint Checker”, never as a result.

• Node.js: unsealResult(sealedResult, [keyA, keyB]) from @fingerprintchecker/node.
• Python: unseal_result(sealed_result, [key_a, key_b]) from fpchecker (pip install fingerprintchecker).
• Go: fpchecker.UnsealResult(sealedResult, []string{keyA, keyB}).

import { unsealResult, SealedResultError } from '@fingerprintchecker/node';

// keys: every active key, base64 as shown once in the console (active and previous during a rotation).
const keys = [process.env.FPC_SEALED_KEY, process.env.FPC_SEALED_KEY_PREVIOUS].filter(Boolean);

try {
  const result = unsealResult(req.body.sealedResult, keys);
  if (result.projectId !== process.env.FPCHECKER_PROJECT_ID) throw new Error('not our project');
  if (Date.now() - result.timestamp > 5 * 60 * 1000) throw new Error('too old'); // timestamp is Unix milliseconds
  if (!(await rememberOnce(result.eventId))) throw new Error('eventId already used'); // your store; or match result.linkedId to the signed-in user
  // This proves origin only. To grant a trial, coupon or credit, call eligibility with a fresh attestation.
  // result: { version, eventId, visitorId, projectId, linkedId, tags, timestamp, platform, proofStatus }
} catch (err) {
  if (!(err instanceof SealedResultError)) throw err; // code: bad_format, unknown_key, decrypt_failed, invalid_key, unsupported_version
  // Not from FingerPrint Checker: refuse, or fall back to GET /v1/events/{eventId}.
}

Client-side result cache

The web agent package can keep a short-lived copy of the last identify result so a page that identifies the same user again does not call the API every time. It is off by default. Turn it on per call with cache: { ttlSeconds, storage }, where ttlSeconds is 1 to 3600 and storage is memory, session or local. Without cache, or with cache: false, every identify goes to the server.

A cached result belongs to an earlier identify. It returns eventId and sealedResult with fromCache: true and no attestation, so it can never be used for eligibility or quota. Never use a cached result for a decision about eligibility or quota: pass cache: false there to force a fresh request, with a new intent token.

Only eventId and sealedResult are stored, never the attestation. The key is built from your publishable key, linkedId and tags; the raw linkedId is not written to storage. An expired or malformed entry counts as a miss, and a storage error (private mode, blocked storage) also counts as a miss, so identify keeps working.

// Fine for showing a returning user a welcome screen: no decision depends on it.
const seen = await fp.identify({ intentToken, linkedId: userId, cache: { ttlSeconds: 300, storage: 'session' } });
if (seen.fromCache) {
  // seen.attestation is undefined here. Do not send this to /v1/eligibility or /v1/quota.
}

// Before any decision: force a fresh identify, then send its attestation to your backend.
const fresh = await fp.identify({ intentToken: newIntentToken, cache: false });

Server SDKs

Three server SDKs wrap the backend endpoints, so you do not write the HTTP calls yourself: @fingerprintchecker/node for Node.js 18 and later, fingerprintchecker (import name fpchecker) for Python 3.9 and later, and the Go module github.com/AndrewYukon/FingerPrintChecker/server/go. Each has one method per operation in the OpenAPI file (createIntent, checkEligibility, checkQuota, searchEvents and so on, in the naming style of the language), opens sealed results and verifies webhook signatures.

They send your secret key only in the X-Secret-Key header, never follow redirects, and retry only GET requests. A 2xx answer is returned as data, including a refusal such as ok: false, so always check the body. A non-2xx answer throws an API error that carries the status and the error code.

Install commands and a minimal example for every SDK, browser and mobile ones included, are on the SDK libraries page (/sdk-libraries).

import os
from fpchecker import FpChecker, FpCheckerApiError

fp = FpChecker(os.environ["FPCHECKER_SECRET_KEY"])
try:
    intent = fp.create_intent({"purpose": "claim:trial"})
except FpCheckerApiError as err:
    raise RuntimeError(f"intent failed: {err.status} {err.code}") from err
token = intent["intentToken"]  # give this to the web agent or the mobile SDK

Webhooks

Add up to 3 HTTPS endpoints per project in the console (Webhooks and retention). The URL must use https on port 443 and a public hostname, not an IP address. Every identify is POSTed to each enabled endpoint as the same event JSON the API returns ("v": 1). Use eventId to ignore duplicates.

The signing secret (whsec_…) is shown once when you add the endpoint and again only when you rotate it. Rotation takes effect immediately, with no grace period. Send test event posts a sample event marked "test": true.

Answer with any 2xx within 3 seconds. Other answers and timeouts are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours (6 attempts in all), then marked failed. Redirects are not followed. An endpoint that fails every delivery for 3 days is disabled automatically; the console shows why and keeps the last 50 deliveries.

Each request carries FPC-Signature, FPC-Event-Id, FPC-Delivery-Id and User-Agent: FPChecker-Webhooks/1. Verify the signature on the raw body before you parse it.

OpenAPI file

The customer-facing API is described in an OpenAPI 3.1 file: identify, intents, eligibility, quota, subjects, feedback, claim flags, events, visitors, health, status and the webhook payload. Each operation has an operationId that the server SDKs use as the method name. It lists no admin or console routes.

Download it from /developers/openapi.yaml and load it in your own tooling or client generator. The production API does not serve /openapi.json or /docs: this file is the contract, and the copy here names the API release it came from in its first line.

Management API

The Management API lets your own tooling do what you would otherwise click through in the console. It acts on the whole account, unlike a project’s secret key, which works on one project. Every route is under https://api.fpchecker.com/v1/management/ and takes a management key (mk_…) as a bearer token.

Owners and admins create management keys in the console at /console/api-keys. A key is shown once, has a read or write scope, and can expire after 30, 90 or 365 days. A read key can call every GET route and the ruleset dry run; a write key can also create, change, rotate and delete. A key sees only its own account’s projects, and a project that is not yours answers exactly like one that does not exist.

Rate limits are 120 reads and 30 writes a minute per account, shared by all keys. Over the limit is a 429 with Retry-After: 60, and a 429 changes nothing, so retrying is safe.

What it does: projects and environments, key rotation, webhooks and rules, plus reading usage, the audit log, events and visitors. It cannot buy credits, manage members or create management keys. Those stay in the console, and a request for them answers 404. Changes made with a management key are recorded in the account audit log with the key as the actor.

The full reference, with every route and answer, is the OpenAPI file below (tag Management). To use the API from a terminal or an AI assistant instead of writing HTTP calls, see Build with AI.

• GET /v1/management/account, /usage and /audit: status and credit balance, billed calls per day, project and endpoint, and the audit log (newest first).
• GET and POST /v1/management/projects, then GET, PATCH and DELETE on /projects/{id}: list, create (the new keys are in the answer only), read, change and delete a never-used project.
• POST /projects/{id}/rotate, POST /projects/{id}/environments and POST /projects/{id}/copy-settings: replace a key, add an environment such as staging, promote tested settings between environments.
• GET and POST /projects/{id}/webhooks, with PATCH, DELETE and rotate on a single endpoint; GET and PUT /projects/{id}/ruleset (a stale save is 409 version_conflict) and POST /projects/{id}/ruleset/test for a dry run.
• GET /projects/{id}/events, /events/{eventId} and /visitors/{visitorId}: the same events and filters as GET /v1/events.

curl https://api.fpchecker.com/v1/management/projects   -H "Authorization: Bearer $FPCHECKER_MANAGEMENT_KEY"
# Authorization: Bearer mk_…   (a failed key is always { "ok": false, "error": "invalid_management_key" })