Skip to content

Platform

App Check

Tested with:Beta on Databasezy · Databasezy API v1

A publishable key is public: anyone can copy it out of your app and script your project’s endpoint. App Check adds a second, short-lived credential that only a genuine copy of your app can get. Your app proves itself to its platform (Google Play, Apple, a CAPTCHA provider or your own service), trades that proof for a Databasezy App Check token, and sends the token with every request. The project’s edge checks it before the request reaches the service.

Use the complete endpoint from Project settings, including its port. Examples below use https://<ref>.us-east.databasezy.com:8443; replace that base URL with your project’s actual endpoint. The same base URL is used for exchange, challenge and JWKS requests.

  1. You register each app in Platform services → App Check (or with the API): its provider and public identifiers, plus the provider’s credential where it needs one. Credentials are write-only and kept in your project’s cell.

  2. The app gets an attestation from its platform and calls the exchange on your project endpoint, POST https://<ref>.us-east.databasezy.com:8443/app-check/v1/exchange, with your publishable key. The exchange verifies the attestation with the provider and answers with an App Check token that lives 15 to 30 minutes (30 by default).

  3. The app sends the token as the X-App-Check header with every request (realtime WebSockets: the app_check query parameter) and gets a new one before it expires.

  4. For each service you choose a mode: off, monitor (the token is checked and counted, every request is served) or enforce (a request without a valid token gets 403 before the service sees it).

ServicePathsNot checked
Auth/auth/v1email links, OAuth and SAML callbacks, discovery (auth: none paths)
Data API/rest/v1, /graphql/v1
Storage/storage/v1public objects and signed URLs (/object/public, /object/sign, /object/upload/sign, /render/image/...)
Functions/functions/v1
Realtime/realtime/v1

Your servers are never asked for a token: requests with a secret key or a service_role JWT (including the one functions get) pass, as do the portal’s own tools. The exchange itself (/app-check/v1) is never checked. Third-party webhooks that call a function cannot attest: keep functions in monitor or off if you rely on them, or call them with a secret key.

ProviderPlatformYou registerCredential
play_integrityAndroid (Google Play)package name, SHA-256 of the app signing certificate (1-5), minimum device verdict (basic, device (default) or strong)a Google Cloud service account JSON key with the Play Integrity API, linked in the Play Console
app_attestiOS 14+, iPadOSTeam ID, bundle ID, environment (production or development)none (verified against Apple’s App Attestation root)
device_checkolder iOS devicesTeam ID, key ID, optional bundle ID, environmentthe DeviceCheck private key (.p8)
turnstilewebsite key, optional hostnames and actionthe Turnstile secret key
recaptchawebsite key, Google Cloud project id, minimum score (0.1-0.9, default 0.5), optional hostnames and actiona Google Cloud API key with the reCAPTCHA Enterprise API
custom_jwtanythingthe issuer (iss), audience (aud) and public keys (inline JWKS, never fetched) of your own attestation servicenone

App Attest is the strongest choice on iOS; DeviceCheck only proves a genuine Apple device running one of your team’s apps. A project has at most 20 apps.

Every exchange takes the publishable key as apikey. Play Integrity and App Attest bind the attestation to a one-time challenge (five minutes, single use):

challenge
curl -sX POST "https://<ref>.us-east.databasezy.com:8443/app-check/v1/challenge" \
-H "apikey: $PUBLISHABLE_KEY" -H "Content-Type: application/json" \
-d '{"app_id":"aca_..."}'
# {"challenge":"q3Jz...","expires_in":300}
app-check.js
// Render the Turnstile widget with your site key; its callback gets turnstileToken.
async function appCheckToken(turnstileToken) {
const res = await fetch("https://<ref>.us-east.databasezy.com:8443/app-check/v1/exchange", {
method: "POST",
headers: { apikey: PUBLISHABLE_KEY, "Content-Type": "application/json" },
body: JSON.stringify({ app_id: "aca_...", token: turnstileToken }),
});
if (!res.ok) throw new Error((await res.json()).code);
return res.json(); // { token, ttl_seconds, expires_at }
}
// supabase-js: add the header to every request (a custom fetch can refresh it).
const supabase = createClient(PROJECT_URL, PUBLISHABLE_KEY, {
global: { headers: { "X-App-Check": token } },
});

reCAPTCHA Enterprise works the same with grecaptcha.enterprise.execute(siteKey, { action }) as the token.

The answer:

{ "token": "eyJhbGciOiJFUzI1NiIs...", "ttl_seconds": 1800, "expires_at": "2026-10-14T12:30:00Z" }
StatuscodeMeaning
400malformednot an attestation of the app’s provider
403rejected, unknown_appthe provider (or our checks) refused it, or the app is not registered
403replayedthe attestation or challenge was used before
403expiredthe attestation is older than five minutes
429rate_limitedmore than 30 exchanges (60 challenges) a minute from one address
503provider_unavailablethe provider could not be reached: retry after Retry-After
503provider_misconfiguredthe provider refused the app’s credential or registration: fix it in the portal

Start every service in monitor and ship app versions that send the token. Each checked request carries its outcome (valid, missing, invalid, expired, unknown_app, valid_debug, debug_revoked, …) in the app_check attribute of its entry in Logs; when old app versions have faded out, switch the service to enforce. A refused request is a 403 problem with X-App-Check-Error: missing, invalid or expired (refresh the token on expired).

shell
zb api PUT /v1/orgs/{org}/projects/<project-id>/app-check -d '{"modes": {"data": "monitor", "storage": "monitor"}}'
zb api PUT /v1/orgs/{org}/projects/<project-id>/app-check -d '{"modes": {"data": "enforce"}}'

Enforcing needs at least one registered app, and the last app of an enforcing project cannot be removed (switch the services back first). Changing enforcement is audited and recorded as the security event app_check.enforcement_changed; switching back to monitor or off works at any time, without support.

Relaxing needs a recent second factor. Any change that relaxes App Check needs a person who verified their second factor in the last 15 minutes, and API keys cannot make it at all:

  • a service from enforce to monitor or off, or from monitor to off;
  • turning monitor fail-open or debug mode on, or creating a debug token;
  • registering, changing or removing an app while a service is enforced.

Without a recent second factor the API answers 403 with the problem type mfa_required (the portal asks for your second factor and brings you back); an API key gets 403 forbidden. Tightening (off to monitor to enforce, revoking a debug token) needs neither. A relaxing change is recorded as a high-severity security event.

Provider outages. By default a provider outage fails closed: the exchange answers 503 and enforced services keep refusing requests without a token. With monitor fail-open on, the exchange issues five-minute degraded tokens while the provider is down; monitored services count them as valid_degraded, enforced services always refuse them.

Emulators, simulators and CI cannot attest. Turn debug mode on, create a debug token for an app (shown once, 1-90 days, at most 20 live) and exchange it with "provider": "debug":

shell
curl -sX POST "https://<ref>.us-east.databasezy.com:8443/app-check/v1/exchange" \
-H "apikey: $PUBLISHABLE_KEY" -H "Content-Type: application/json" \
-d '{"app_id":"aca_...","provider":"debug","token":"'"$APP_CHECK_DEBUG_TOKEN"'"}'

Debug tokens are accepted by monitored services only: the moment a service is enforced, they stop working there, with no grace period. Revoking a token, or switching debug mode off, refuses its App Check tokens as soon as the edge sees the change. Never ship a debug token in an app.

App Check tokens are ES256 JWTs signed with your project’s keys (rotated with them): verify them with https://<ref>.us-east.databasezy.com:8443/auth/v1/.well-known/jwks.json, require the header typ: zb-app-check+jwt, and check aud and iss are zb-app-check:<project id>. The claims name the app (app), the provider (prv), a debug token (dbg) or a degraded token (deg). Requests that passed the edge also carry the verified app id to your functions as the X-Zb-App header.

MethodPathPermission
GET/v1/orgs/{org}/projects/{project}/app-checkprojects:read
PUT/v1/orgs/{org}/projects/{project}/app-checkproject_keys:manage
POST/v1/orgs/{org}/projects/{project}/app-check/appsproject_keys:manage
PATCH, DELETE/v1/orgs/{org}/projects/{project}/app-check/apps/{app}project_keys:manage
POST/v1/orgs/{org}/projects/{project}/app-check/debug-tokensproject_keys:manage
DELETE/v1/orgs/{org}/projects/{project}/app-check/debug-tokens/{token}project_keys:manage

PUT takes modes (auth, data, storage, functions, realtime: off, monitor, enforce; another key is refused), token_ttl_seconds (900-1800), debug_enabled and monitor_fail_open; fields left out keep their value. Relaxing changes also need a recent second factor and a person (see above).

App Check is free on every plan, like Firebase App Check: exchanges and verified requests are not metered or billed. Attestation providers keep their own quotas (for example Play Integrity’s daily request quota on your Google Cloud project).