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.
How it works
Section titled “How it works”-
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.
-
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). -
The app sends the token as the
X-App-Checkheader with every request (realtime WebSockets: theapp_checkquery parameter) and gets a new one before it expires. -
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
403before the service sees it).
| Service | Paths | Not checked |
|---|---|---|
| Auth | /auth/v1 | email links, OAuth and SAML callbacks, discovery (auth: none paths) |
| Data API | /rest/v1, /graphql/v1 | |
| Storage | /storage/v1 | public 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.
Choose a provider
Section titled “Choose a provider”| Provider | Platform | You register | Credential |
|---|---|---|---|
play_integrity | Android (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_attest | iOS 14+, iPadOS | Team ID, bundle ID, environment (production or development) | none (verified against Apple’s App Attestation root) |
device_check | older iOS devices | Team ID, key ID, optional bundle ID, environment | the DeviceCheck private key (.p8) |
turnstile | web | site key, optional hostnames and action | the Turnstile secret key |
recaptcha | web | site key, Google Cloud project id, minimum score (0.1-0.9, default 0.5), optional hostnames and action | a Google Cloud API key with the reCAPTCHA Enterprise API |
custom_jwt | anything | the issuer (iss), audience (aud) and public keys (inline JWKS, never fetched) of your own attestation service | none |
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.
Exchange an attestation
Section titled “Exchange an attestation”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):
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}// 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.
// 1. A challenge from /app-check/v1/challenge becomes the nonce (classic request).val integrity = IntegrityManagerFactory.create(context)val response = integrity.requestIntegrityToken( IntegrityTokenRequest.builder().setNonce(challenge).build()).await()// 2. Exchange it.val body = """{"app_id":"aca_...","token":"${response.token()}","challenge":"$challenge"}"""// POST body to https://<ref>.us-east.databasezy.com:8443/app-check/v1/exchange with header apikey// -> {"token":"...","ttl_seconds":1800}; send it as X-App-Check.A standard integrity request works too: pass the challenge as setRequestHash(challenge).
import CryptoKitimport DeviceCheck
let service = DCAppAttestService.shared// First launch: create and attest a key (keep keyId in the keychain).let keyId = try await service.generateKey()let hash = Data(SHA256.hash(data: Data(challenge.utf8)))let attestation = try await service.attestKey(keyId, clientDataHash: hash)// POST {"app_id":"aca_...","key_id":keyId,"attestation":attestation.base64EncodedString(),"challenge":challenge}// -> {"token":"...","artifact":"..."} keep the artifact in the keychain.
// Every later exchange: a fresh challenge, an assertion and the artifact.let assertion = try await service.generateAssertion(keyId, clientDataHash: Data(SHA256.hash(data: Data(next.utf8))))// POST {"app_id":"aca_...","artifact":artifact,"assertion":assertion.base64EncodedString(),"challenge":next}For DeviceCheck send {"app_id":"aca_...","token":<DCDevice token, base64>}.
Your attestation service signs a JWT with one of the keys you registered: iss and aud as registered, iat,
exp at most 10 minutes later and a unique jti (each token is accepted once). The app sends it as
{"app_id":"aca_...","token":"<jwt>"}.
The answer:
{ "token": "eyJhbGciOiJFUzI1NiIs...", "ttl_seconds": 1800, "expires_at": "2026-10-14T12:30:00Z" }| Status | code | Meaning |
|---|---|---|
| 400 | malformed | not an attestation of the app’s provider |
| 403 | rejected, unknown_app | the provider (or our checks) refused it, or the app is not registered |
| 403 | replayed | the attestation or challenge was used before |
| 403 | expired | the attestation is older than five minutes |
| 429 | rate_limited | more than 30 exchanges (60 challenges) a minute from one address |
| 503 | provider_unavailable | the provider could not be reached: retry after Retry-After |
| 503 | provider_misconfigured | the provider refused the app’s credential or registration: fix it in the portal |
Monitor, then enforce
Section titled “Monitor, then enforce”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).
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.
Debug tokens
Section titled “Debug tokens”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":
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.
Verify tokens in your own backend
Section titled “Verify tokens in your own backend”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.
| Method | Path | Permission |
|---|---|---|
GET | /v1/orgs/{org}/projects/{project}/app-check | projects:read |
PUT | /v1/orgs/{org}/projects/{project}/app-check | project_keys:manage |
POST | /v1/orgs/{org}/projects/{project}/app-check/apps | project_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-tokens | project_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).
Pricing
Section titled “Pricing”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).