Deploying the verifier
For platform and ops engineers. At the end of this page, trustpincloud/attest-verifier:1.0.0 runs in your infrastructure behind HTTPS, serves your published policy, and passes its checks. Your apps can then attest against it.
The verifier is a service you run next to your API. It checks the evidence your apps send against the policy you published in the console, and issues the short-lived tokens your API verifies. TrustPin runs no attestation service: its only runtime role is serving your signed policy (attest.jws.b64) from its CDN.
The verifier ships as one container image, trustpincloud/attest-verifier, for linux/amd64 and linux/arm64, signed with cosign. It is configured only through environment variables; there are no configuration files.
How it fits in your network
The verifier has two listeners. The public port (8080) serves the apps and your API’s key lookups, behind your gateway or load balancer, which provides TLS, rate limiting and IP filtering. The monitor port (9090) is read-only status for probes and Prometheus, and never leaves your private network.
Open these connections:
| Direction | From, to | When |
|---|---|---|
| In | Your gateway or load balancer to the verifier’s port 8080 | Always |
| In | Probes and Prometheus to port 9090, on your private network | Always |
| Out | HTTPS to cdn.trustpin.cloud, cdn.trustpin.io and cdn.trustpin.mobile: your policy | Always, unless you host the policy yourself |
| Out | HTTPS to android.googleapis.com: Google’s attestation revocation list, daily | Always. Without it, /readyz reports degraded once the copy built into the image is 7 days old |
| Out | HTTPS to playintegrity.googleapis.com and the token_uri of your service-account key (normally oauth2.googleapis.com) | Only when the policy accepts Play Integrity evidence |
| Out | Your Redis or Postgres | Only with a shared store |
Apple App Attest and Android Key Attestation evidence is checked inside the verifier, with no outside call. An outbound proxy works through the standard HTTPS_PROXY and NO_PROXY variables.
Before you start
- A published policy. The project’s Attestation page shows the version as published on the Policy tab. Without it, the verifier exits with code
3. See Setting up apps and the policy. - The verifier’s public URL, for each environment:
https://on port 443 with a DNS host name, for examplehttps://attest.example.com, or a path on an existing host, for examplehttps://api.example.com/attest. Create the DNS record and the TLS certificate on your gateway or load balancer. - A secret store, such as a vault or KMS, from which secrets are injected as environment variables when the container starts.
- Docker Compose or Kubernetes, or any platform that runs a container with environment variables.
- NTP on every host. Challenge and token lifetimes depend on the clock.
- For Play Integrity only: the JSON key of the Google service account you created during setup.
1. Download the deployment bundle
The bundle fills in every identifier of your project and leaves only the secrets as placeholders.
- Open the project’s Attestation page, Deployment tab.
- Under Environments, give each environment a name (for example
stagingorproduction) and the verifier’s public URL. Fill in Google Cloud project number and Header the apps bind tokens to if you use them. Choose Save deployment. - Under Deployment bundle, choose a Format and, with several environments, the Environment. Choose Download.
The environment’s URL becomes the issuer (iss) of every token and the base of the verifier’s key and discovery URLs, so set it to the final public URL, including any path. Your apps are configured with the same URL.
| Format | Download | Files |
|---|---|---|
| Docker Compose | attest-verifier-<environment>-compose.zip | docker-compose.yml, .env.example, README.md |
| Kubernetes | attest-verifier-<environment>-kubernetes.zip | deployment.yaml (ConfigMap, Deployment, PodDisruptionBudget), service.yaml (Service and an example Ingress), secret.example.yaml, README.md |
| .env file only | .env.example | The variables, for any other platform |
Each README.md includes a checklist for Apple, Google Cloud, Play Console and your gateway, written for your policy.
The CLI writes the same files:
trustpin-cli projects attestation bundle <organization id> <project id> \
--format compose --environment staging --out verifier/--format is compose, kubernetes or env. Without --out, the files are printed.
2. Create the secrets
Generate each secret with the image itself:
docker run --rm trustpincloud/attest-verifier:1.0.0 keygen # TRUSTPIN_TOKEN_SIGNING_KEYS
docker run --rm trustpincloud/attest-verifier:1.0.0 keygen --secret # TRUSTPIN_CHALLENGE_SECRETS
docker run --rm trustpincloud/attest-verifier:1.0.0 keygen --secret # TRUSTPIN_MONITOR_API_KEYEach command prints the value on stdout and a hint on stderr; keygen also prints the key’s kid. Add --json for machine output.
| Variable | What it is |
|---|---|
TRUSTPIN_TOKEN_SIGNING_KEYS | Signs the tokens and key certificates the verifier issues. Comma-separated base64 PKCS#8 EC P-256 keys: the first signs, all of them verify and appear in the JWKS. Unrelated to the TrustPin project key |
TRUSTPIN_CHALLENGE_SECRETS | Signs challenges. Comma-separated base64 secrets of at least 32 bytes: the first signs, all of them verify |
TRUSTPIN_MONITOR_API_KEY | Protects the monitor port: at least 16 characters. Recommended whenever the port is reachable beyond the container |
TRUSTPIN_PLAY_INTEGRITY_CREDENTIALS | Only when the policy accepts Play Integrity evidence: the service-account JSON key, base64 encoded (base64 < key.json | tr -d '\n'). Alternatively, mount the file and set GOOGLE_APPLICATION_CREDENTIALS to its path. Required when Evidence is Play Integrity only or Both, and it must be set before you publish such a policy: a verifier without it refuses that policy, keeps the previous version, and exits with code 2 on restart. With Either, Android devices pass on Key Attestation alone without it |
Rules:
- Every instance of one environment uses the same values. Every environment (staging, production, each project) has its own.
- Keep them in your secret store and inject them at start. Never bake them into an image or commit them.
- Replace every
<…>placeholder. The verifier refuses a monitor API key that still starts with<.
Without signing keys or challenge secrets, the verifier generates them in memory and logs a warning. That suits a quick local test only: every restart then forces every device to attest again, and instances don’t accept each other’s tokens.
3. Choose the store
The store keeps one-time challenges and App Attest counters, which is how the verifier refuses replayed requests. TRUSTPIN_STORE_URL selects it:
| Deployment | TRUSTPIN_STORE_URL |
|---|---|
| One instance | Unset: memory://, the default. Kept in the process and lost on restart |
| Several instances | A store all instances share: rediss://… (also rediss-sentinel://… and rediss-cluster://…), or postgres://…?sslmode=verify-full |
| No replay protection | none: challenges aren’t one-time and App Attest counters aren’t checked |
-
Several instances on
memory://each accept a challenge once. Startup logs a warning whenever signing keys are set while the store ismemory://; with one instance, that warning is expected. -
Off the verifier’s host, connect with verified TLS. The plaintext forms (
redis://, or Postgres withoutsslmode=verify-full) work, but startup warns. -
Postgres: create the tables before the first start. The verifier never runs DDL, so its database role needs
SELECT,INSERT,UPDATEandDELETEonly:docker run --rm trustpincloud/attest-verifier:1.0.0 migrations print > attest-schema.sql psql "<admin connection URL>" -f attest-schema.sql -
One Redis or Postgres can serve several verifier deployments: every key and row is namespaced by organization and project.
-
If the store fails,
/v1/attestand/v1/tokenanswer503 not_readyuntil it recovers (TRUSTPIN_STORE_FAILURE=closed, the default).openserves without replay protection instead.
The bundle runs one instance. To run more, set the store first, then raise the replicas; on Kubernetes, also switch the PodDisruptionBudget to minAvailable: 1. See Scaling.
4. Fill in and check the configuration
Put the secrets and, if needed, TRUSTPIN_STORE_URL where your format expects them, then run attest-verifier check. It runs the startup sequence without serving: configuration, project key, signing keys, the policy fetch, the policy against your configuration, the policy cache, the clock, the store and its schema, and the Google credentials.
Docker Compose:
cp .env.example .env # add the secrets, or inject them from your secret store
docker compose run --rm verifier checkKubernetes: create the Secret named attest-verifier with the keys of secret.example.yaml, from your secret store (External Secrets, a CSI driver) or from a filled-in copy you never commit. check runs inside the pod once it is deployed, in step 5.
.env file only: set the variables on your platform. To check on any Docker host:
docker run --rm --env-file .env trustpincloud/attest-verifier:1.0.0 checkOlder bundles wrapped the values in single quotes, which docker run --env-file keeps. If yours does, remove them first: sed "s/='\(.*\)'$/=\1/" .env > verifier.env, and pass verifier.env.
Each line of the report starts with [ok], [warn], [skip] or [FAIL], and the last line gives the result:
[ok] policy version 3 from cdn; mode monitor; apple (1 app(s))
[ok] compatibility policy and configuration agree
[ok] clock within 30s of cdn.trustpin.cloud
[ok] store memory (in-process, the default; ...)
Result: ready to serve (exit 0)check and the verifier itself exit with the same codes:
| Exit code | Meaning | What to do |
|---|---|---|
0 | Ready (check), or a clean shutdown (serve) | Nothing |
1 | Startup failure: no policy source reachable within TRUSTPIN_STARTUP_TIMEOUT and no cache, a policy that fails validation, or a store that is unreachable or whose schema is behind | Read the [FAIL] line or the startup log event |
2 | Configuration error, including a policy that needs Play Integrity credentials this instance lacks | Every problem is listed; fix them all |
3 | Attestation is not set up: no policy is published for the project | Sign and publish on the Policy tab |
Check: check ends with Result: ready to serve (exit 0). Read every [warn] line.
5. Start it
Docker Compose:
docker compose up -dKubernetes:
kubectl apply -f deployment.yaml -f service.yaml
kubectl rollout status deploy/attest-verifier
kubectl exec deploy/attest-verifier -- /attest-verifier checkOther platforms: run the image with the variables, and map its ports:
- Publish port 8080 to your load balancer. Keep port 9090 private.
- To reach port 9090 from outside the container, set
TRUSTPIN_MONITOR_LISTEN_ADDR=:9090together withTRUSTPIN_MONITOR_API_KEY. The default,127.0.0.1:9090, answers only inside the container. The Compose and Kubernetes bundles already set:9090. - Liveness:
GET /healthzon either port. Readiness:GET /readyzon port 9090. The image has no shell orcurl, so probe from outside the container. A load balancer that can only reach the public port usesGET /healthzon 8080. - Optionally, set
TRUSTPIN_POLICY_CACHE_DIRto a persistent directory writable by user 65532. The last good policy is kept there, so an instance can start while the CDN is unreachable. The bundles set/cache. - On stop, the verifier drains requests for
TRUSTPIN_SHUTDOWN_TIMEOUT(30 s) afterSIGTERM. Give it a longer grace period.
At startup, the verifier downloads your signed policy, validates its signature with TRUSTPIN_PROJECT_PUBLIC_KEY, and starts both listeners. It retries an unreachable CDN for up to TRUSTPIN_STARTUP_TIMEOUT (60 s).
6. Route HTTPS to it
On your gateway or load balancer:
- Serve the environment’s URL over HTTPS on port 443, with a certificate for its host.
- Forward
/v1/and/.well-known/to the verifier’s port 8080. If the URL has a path, such as/attest, strip it before forwarding: the verifier serves/v1/…and/.well-known/…at its root. The Kubernetes bundle’s example Ingress needs your controller’s rewrite annotation for this. - Never route port 9090.
- If you set
TRUSTPIN_RATE_LIMIT, setTRUSTPIN_TRUSTED_PROXIESto your gateway’s addresses. Otherwise the verifier sees the gateway as the only client.
TLS normally ends at the gateway. To encrypt the hop to the verifier too, or require client certificates, see TRUSTPIN_TLS_* in the configuration reference.
7. Verify the deployment
Run the first two checks from outside your network, against the environment’s URL, as an app would.
-
A challenge carries your published policy version:
curl -s https://attest.example.com/v1/challenge{"contractVersion":2,"challenge":"…","expiresAt":1792400300,"serverTime":1792400000,"policyVersion":3,"requires":{…}}policyVersionequals the version on the Policy tab, andcontractVersionis2. -
The keys and the discovery document are public:
curl -s https://attest.example.com/.well-known/jwks.json curl -s https://attest.example.com/.well-known/openid-configurationThe JWKS lists one key per entry of
TRUSTPIN_TOKEN_SIGNING_KEYS, with thekidthatkeygenprinted. The discovery document’sissueris the environment’s URL. -
/readyzreportsok. On a Compose host, which publishes the monitor port on the host’s loopback only, use theTRUSTPIN_MONITOR_API_KEYvalue from your.env:curl -s -u monitor:'<TRUSTPIN_MONITOR_API_KEY>' http://127.0.0.1:9090/readyzOn Kubernetes, run
kubectl port-forward deploy/attest-verifier 9090:9090first.degradedwith onlydebugTokensconfigured is expected on staging. Any otherdegradedorunavailable: see Readiness. -
In the console, open the Status tab, find the environment under Verifier checks, and choose Check now. TrustPin’s backend connects to your verifier as an app would: TLS, pinning, issuer, signing keys, and a challenge with the applied policy version. Its Pinned for the SDKs step passes, and the environment’s row reads
pinned, once you register the domain, in the next step.
A few hours later, the Verifier fleet card shows the verifier fetching the policy, and the Go-live checklist ticks “Verifier deployed and fetching the policy”.
8. Register the verifier’s domain
The SDKs pin their calls to the verifier, and in strict mode they refuse a host that isn’t registered in the project. Register the verifier’s host, for example attest.example.com, and publish the pin configuration: see Registering the verifier’s domain.
Check: Check now on the Status tab passes Pinned for the SDKs, and the environment’s row reads pinned.
Staging and production
One TrustPin project serves every environment. The policy lists your apps once and is the same for all of them; each environment runs its own verifier deployment, with its own URL, issuer, secrets and domain registration.
Run stages 1 to 5 against staging first. Then, for production:
- On the Deployment tab, choose Add environment, name it
production, give its public URL, and Save deployment. The policy version doesn’t change. - Download the bundle for the
productionEnvironment and repeat steps 2 to 8 of this page with new secrets. Never setTRUSTPIN_DEBUG_TOKEN_HASHESthere. - Give the production API the production values from the Go-live guide, with
productionpicked in Environment. Tokens from the staging verifier are refused there, and the other way round. - Point release builds at the production verifier: see the SDK page’s configuration section (iOS and macOS, Android).
Check: Check now passes for both environments, and a release build’s request to the production API logs outcome pass with env production.
Staging: debug tokens
Simulators and emulators cannot produce platform evidence. To test with them, on the staging verifier only:
-
Turn on Allow debug tokens in the policy, and publish. Every environment shares the policy, but only a verifier with debug token hashes accepts debug tokens.
-
Generate a token and its hash:
docker run --rm trustpincloud/attest-verifier:1.0.0 keygen --debug-tokenLine 1 is the token, for developers’ run configuration; it never goes in an app bundle. Line 2 is the hash.
-
Set
TRUSTPIN_DEBUG_TOKEN_HASHESto the hash (several are comma-separated) and restart.
Tokens issued this way carry tp.plat and tp.env debug, and your production API must refuse them. While hashes are set, /readyz reports degraded. Never set them in production.
Configuration reference
Required
The bundle fills these in.
| Variable | Description |
|---|---|
TRUSTPIN_ORG_ID | Your organization ID |
TRUSTPIN_PROJECT_ID | Your project ID |
TRUSTPIN_PROJECT_PUBLIC_KEY | The project public key (base64 DER), the same value your apps use. It never changes for the life of the project |
Secrets
See Create the secrets.
| Variable | Default | Description |
|---|---|---|
TRUSTPIN_TOKEN_SIGNING_KEYS | Generated in memory | Token and key-certificate signing keys. To rotate them, see Rotating keys and secrets |
TRUSTPIN_CHALLENGE_SECRETS | Generated in memory | Challenge secrets |
TRUSTPIN_MONITOR_API_KEY | None: the monitor port is open | Key for the monitor port, at least 16 characters, sent as the Basic password or a Bearer token. /healthz and the status of /readyz stay open for probes |
TRUSTPIN_PLAY_INTEGRITY_CREDENTIALS | None | Base64 Google service-account JSON key |
GOOGLE_APPLICATION_CREDENTIALS | None | Path of the same key as a file, used when the variable above is unset |
TRUSTPIN_DEBUG_TOKEN_HASHES | None | Comma-separated base64url(SHA-256(debug token)). Staging only |
Tokens
| Variable | Default | Description |
|---|---|---|
TRUSTPIN_TOKEN_ISSUER | tprn::attest::<organization id>::<project id> | iss of issued tokens. An https:// URL also turns on /.well-known/openid-configuration. The bundle sets the environment’s URL |
TRUSTPIN_TOKEN_AUDIENCE | tprn::project::<organization id>::<project id> | aud of access tokens. Your API expects exactly this value |
Store
| Variable | Default | Description |
|---|---|---|
TRUSTPIN_STORE_URL | memory:// | See Choose the store. For Postgres high availability, a multi-host URL with target_session_attrs=read-write follows the primary |
TRUSTPIN_STORE_FAILURE | closed | closed answers 503 not_ready while the store fails; open serves without replay protection |
TRUSTPIN_STORE_TIMEOUT | 2s | Bound on each store call. A slower store counts as failed |
Policy loading
| Variable | Default | Description |
|---|---|---|
TRUSTPIN_POLICY_REFRESH_INTERVAL | 5m | How often the policy is fetched again, each wait ±10%. A new published version is live within one interval |
TRUSTPIN_POLICY_CACHE_DIR | None | Directory for the last good policy. It lets an instance start while the CDN is unreachable, and an older policy is never accepted after it |
TRUSTPIN_STARTUP_TIMEOUT | 60s | How long startup retries an unreachable CDN |
TRUSTPIN_ATTEST_CONFIGURATION_URL | None | An https:// URL of your own copy of the signed policy file, tried first, with the TrustPin CDNs as fallback. Keep it in step with every publish. Air-gapped deployments set it and block the CDNs |
Listeners and network
| Variable | Default | Description |
|---|---|---|
TRUSTPIN_LISTEN_ADDR | :8080 | Public listener |
TRUSTPIN_MONITOR_LISTEN_ADDR | 127.0.0.1:9090 | Monitor listener. Set :9090, with TRUSTPIN_MONITOR_API_KEY, when probes or Prometheus connect from outside the container. Never expose it publicly |
TRUSTPIN_TLS_CERT_FILE, TRUSTPIN_TLS_KEY_FILE | None: plain HTTP | PEM certificate chain and key. Both listeners then serve HTTPS, so probes and Prometheus must use https. Changed files are picked up without a restart |
TRUSTPIN_TLS_CLIENT_CA_FILE | None | Require client certificates signed by this CA (mutual TLS). Needs the two variables above |
TRUSTPIN_TRUSTED_PROXIES | None: the TCP peer is the client | Comma-separated addresses or CIDRs whose X-Forwarded-For names the client |
TRUSTPIN_SHUTDOWN_TIMEOUT | 30s | Drain time after SIGTERM |
Limits and lifetimes
| Variable | Default | Description |
|---|---|---|
TRUSTPIN_RATE_LIMIT | Off | <n>/s, <n>/m or <n>/h per client IP (IPv6 per /64) on /v1/*; excess gets 429 rate_limited. Defence in depth behind your gateway’s own limit |
TRUSTPIN_KEY_RATE_LIMIT | 60/h | <n>/s, <n>/m, <n>/h or <n>/d per device key, counted per instance; excess gets 429 too_many_attestations, and the SDKs wait as told. none turns it off |
TRUSTPIN_REFUSAL_RETRY_AFTER | 10m | How long a device waits after the verifier refuses its attestation, 1m to 24h |
TRUSTPIN_CHALLENGE_TTL | 5m | How long a challenge is valid |
TRUSTPIN_ASSERTION_NONCE_TTL | 60s | How long an assertion nonce is valid, 10s to 5m |
Logs and tracing
| Variable | Default | Description |
|---|---|---|
TRUSTPIN_LOG_LEVEL | info | debug, info, warn or error |
TRUSTPIN_LOG_FORMAT | json | json or text |
OTEL_EXPORTER_OTLP_ENDPOINT and the other standard OTEL_* variables | Off | OpenTelemetry tracing |
An unknown TRUSTPIN_* variable is ignored with a warning in the log and in check, so check the spelling of any variable you add.
Image, versions and licence
| Tag | Use |
|---|---|
1.0.0 | An exact release. Pin this, or its digest, in anything long-lived |
1.0, 1, latest | Moving tags. Never deploy them |
Verify the image’s signature before you deploy it:
cosign verify trustpincloud/attest-verifier:1.0.0 \
--certificate-identity-regexp '^https://github\.com/trustpin-cloud/cloud-console-attest-verifier/\.github/workflows/release\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+.*$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comattest-verifier version prints the running version.
| SDK | Verifier |
|---|---|
| Swift 7.1.0 | 1.0.0 or later (contract version 2) |
| Kotlin, Flutter and React Native 7.1.x | 1.0.0 or later (contract version 2) |
The verifier is under the TrustPin Binary License Agreement: Attestation Verifier, which ships inside the image. You may run it in your own infrastructure, in any number of instances, while your TrustPin plan is active. Service providers may run it for a client, for that client’s TrustPin projects.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Exit code 3 | No published policy for the project | Sign and publish on the Policy tab, then start again |
Exit code 1, and the policy fails validation | TRUSTPIN_PROJECT_PUBLIC_KEY is not this project’s key | Copy it again from the bundle |
Exit code 1, no policy source reachable | Outbound HTTPS to the TrustPin CDNs is blocked | Allow the outbound connections, or set HTTPS_PROXY |
Exit code 1, schema behind | The Postgres tables are missing or older than the verifier | Apply attest-verifier migrations print |
Exit code 2, “must be 1-128 characters” for TRUSTPIN_ORG_ID | docker run --env-file passed the quotes of an older bundle’s .env file | Remove the quotes, as in step 4 |
Exit code 2, “still the example placeholder” | TRUSTPIN_MONITOR_API_KEY was uncommented without a value | Set a key from keygen --secret |
Exit code 2, Play Integrity credentials missing | Evidence is Play Integrity only or Both | Set TRUSTPIN_PLAY_INTEGRITY_CREDENTIALS |
check warns about the clock | The host clock is more than 30 s off | Synchronise it with NTP |
/v1/challenge answers 404 through the gateway | The gateway forwards the URL’s path to the verifier | Strip the path prefix |
| Port 9090 refuses connections from another container or pod | The monitor port listens on 127.0.0.1 by default | Set TRUSTPIN_MONITOR_LISTEN_ADDR=:9090 with TRUSTPIN_MONITOR_API_KEY |
The app reports verifierUnavailable | The verifier’s domain isn’t registered, and the app pins strictly | Register the domain |
Next steps
- Register and pin the verifier’s domain, if you haven’t yet. Check now on the Status tab then shows Pinned for the SDKs.
- Configure the apps with the verifier’s URL: iOS and macOS, Android, Flutter or React Native.
- Verifying tokens in your API
- Operating the verifier: monitoring, rotation, upgrades and incidents.