Skip to Content
App AttestationDeploying the verifier

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:

DirectionFrom, toWhen
InYour gateway or load balancer to the verifier’s port 8080Always
InProbes and Prometheus to port 9090, on your private networkAlways
OutHTTPS to cdn.trustpin.cloud, cdn.trustpin.io and cdn.trustpin.mobile: your policyAlways, unless you host the policy yourself
OutHTTPS to android.googleapis.com: Google’s attestation revocation list, dailyAlways. Without it, /readyz reports degraded once the copy built into the image is 7 days old
OutHTTPS 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
OutYour Redis or PostgresOnly 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 example https://attest.example.com, or a path on an existing host, for example https://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.

  1. Open the project’s Attestation page, Deployment tab.
  2. Under Environments, give each environment a name (for example staging or production) 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.
  3. 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.

FormatDownloadFiles
Docker Composeattest-verifier-<environment>-compose.zipdocker-compose.yml, .env.example, README.md
Kubernetesattest-verifier-<environment>-kubernetes.zipdeployment.yaml (ConfigMap, Deployment, PodDisruptionBudget), service.yaml (Service and an example Ingress), secret.example.yaml, README.md
.env file only.env.exampleThe 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_KEY

Each command prints the value on stdout and a hint on stderr; keygen also prints the key’s kid. Add --json for machine output.

VariableWhat it is
TRUSTPIN_TOKEN_SIGNING_KEYSSigns 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_SECRETSSigns challenges. Comma-separated base64 secrets of at least 32 bytes: the first signs, all of them verify
TRUSTPIN_MONITOR_API_KEYProtects the monitor port: at least 16 characters. Recommended whenever the port is reachable beyond the container
TRUSTPIN_PLAY_INTEGRITY_CREDENTIALSOnly 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:

DeploymentTRUSTPIN_STORE_URL
One instanceUnset: memory://, the default. Kept in the process and lost on restart
Several instancesA store all instances share: rediss://… (also rediss-sentinel://… and rediss-cluster://…), or postgres://…?sslmode=verify-full
No replay protectionnone: 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 is memory://; with one instance, that warning is expected.

  • Off the verifier’s host, connect with verified TLS. The plaintext forms (redis://, or Postgres without sslmode=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, UPDATE and DELETE only:

    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/attest and /v1/token answer 503 not_ready until it recovers (TRUSTPIN_STORE_FAILURE=closed, the default). open serves 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 check

Kubernetes: 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 check

Older 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 codeMeaningWhat to do
0Ready (check), or a clean shutdown (serve)Nothing
1Startup 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 behindRead the [FAIL] line or the startup log event
2Configuration error, including a policy that needs Play Integrity credentials this instance lacksEvery problem is listed; fix them all
3Attestation is not set up: no policy is published for the projectSign 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 -d

Kubernetes:

kubectl apply -f deployment.yaml -f service.yaml kubectl rollout status deploy/attest-verifier kubectl exec deploy/attest-verifier -- /attest-verifier check

Other 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=:9090 together with TRUSTPIN_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 /healthz on either port. Readiness: GET /readyz on port 9090. The image has no shell or curl, so probe from outside the container. A load balancer that can only reach the public port uses GET /healthz on 8080.
  • Optionally, set TRUSTPIN_POLICY_CACHE_DIR to 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) after SIGTERM. 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:

  1. Serve the environment’s URL over HTTPS on port 443, with a certificate for its host.
  2. 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.
  3. Never route port 9090.
  4. If you set TRUSTPIN_RATE_LIMIT, set TRUSTPIN_TRUSTED_PROXIES to 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.

  1. 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":{…}}

    policyVersion equals the version on the Policy tab, and contractVersion is 2.

  2. 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-configuration

    The JWKS lists one key per entry of TRUSTPIN_TOKEN_SIGNING_KEYS, with the kid that keygen printed. The discovery document’s issuer is the environment’s URL.

  3. /readyz reports ok. On a Compose host, which publishes the monitor port on the host’s loopback only, use the TRUSTPIN_MONITOR_API_KEY value from your .env:

    curl -s -u monitor:'<TRUSTPIN_MONITOR_API_KEY>' http://127.0.0.1:9090/readyz

    On Kubernetes, run kubectl port-forward deploy/attest-verifier 9090:9090 first. degraded with only debugTokens configured is expected on staging. Any other degraded or unavailable: see Readiness.

  4. 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:

  1. On the Deployment tab, choose Add environment, name it production, give its public URL, and Save deployment. The policy version doesn’t change.
  2. Download the bundle for the production Environment and repeat steps 2 to 8 of this page with new secrets. Never set TRUSTPIN_DEBUG_TOKEN_HASHES there.
  3. Give the production API the production values from the Go-live guide, with production picked in Environment. Tokens from the staging verifier are refused there, and the other way round.
  4. 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:

  1. 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.

  2. Generate a token and its hash:

    docker run --rm trustpincloud/attest-verifier:1.0.0 keygen --debug-token

    Line 1 is the token, for developers’ run configuration; it never goes in an app bundle. Line 2 is the hash.

  3. Set TRUSTPIN_DEBUG_TOKEN_HASHES to 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.

VariableDescription
TRUSTPIN_ORG_IDYour organization ID
TRUSTPIN_PROJECT_IDYour project ID
TRUSTPIN_PROJECT_PUBLIC_KEYThe 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.

VariableDefaultDescription
TRUSTPIN_TOKEN_SIGNING_KEYSGenerated in memoryToken and key-certificate signing keys. To rotate them, see Rotating keys and secrets
TRUSTPIN_CHALLENGE_SECRETSGenerated in memoryChallenge secrets
TRUSTPIN_MONITOR_API_KEYNone: the monitor port is openKey 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_CREDENTIALSNoneBase64 Google service-account JSON key
GOOGLE_APPLICATION_CREDENTIALSNonePath of the same key as a file, used when the variable above is unset
TRUSTPIN_DEBUG_TOKEN_HASHESNoneComma-separated base64url(SHA-256(debug token)). Staging only

Tokens

VariableDefaultDescription
TRUSTPIN_TOKEN_ISSUERtprn::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_AUDIENCEtprn::project::<organization id>::<project id>aud of access tokens. Your API expects exactly this value

Store

VariableDefaultDescription
TRUSTPIN_STORE_URLmemory://See Choose the store. For Postgres high availability, a multi-host URL with target_session_attrs=read-write follows the primary
TRUSTPIN_STORE_FAILUREclosedclosed answers 503 not_ready while the store fails; open serves without replay protection
TRUSTPIN_STORE_TIMEOUT2sBound on each store call. A slower store counts as failed

Policy loading

VariableDefaultDescription
TRUSTPIN_POLICY_REFRESH_INTERVAL5mHow often the policy is fetched again, each wait ±10%. A new published version is live within one interval
TRUSTPIN_POLICY_CACHE_DIRNoneDirectory 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_TIMEOUT60sHow long startup retries an unreachable CDN
TRUSTPIN_ATTEST_CONFIGURATION_URLNoneAn 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

VariableDefaultDescription
TRUSTPIN_LISTEN_ADDR:8080Public listener
TRUSTPIN_MONITOR_LISTEN_ADDR127.0.0.1:9090Monitor 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_FILENone: plain HTTPPEM 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_FILENoneRequire client certificates signed by this CA (mutual TLS). Needs the two variables above
TRUSTPIN_TRUSTED_PROXIESNone: the TCP peer is the clientComma-separated addresses or CIDRs whose X-Forwarded-For names the client
TRUSTPIN_SHUTDOWN_TIMEOUT30sDrain time after SIGTERM

Limits and lifetimes

VariableDefaultDescription
TRUSTPIN_RATE_LIMITOff<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_LIMIT60/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_AFTER10mHow long a device waits after the verifier refuses its attestation, 1m to 24h
TRUSTPIN_CHALLENGE_TTL5mHow long a challenge is valid
TRUSTPIN_ASSERTION_NONCE_TTL60sHow long an assertion nonce is valid, 10s to 5m

Logs and tracing

VariableDefaultDescription
TRUSTPIN_LOG_LEVELinfodebug, info, warn or error
TRUSTPIN_LOG_FORMATjsonjson or text
OTEL_EXPORTER_OTLP_ENDPOINT and the other standard OTEL_* variablesOffOpenTelemetry 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

TagUse
1.0.0An exact release. Pin this, or its digest, in anything long-lived
1.0, 1, latestMoving 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.com

attest-verifier version prints the running version.

SDKVerifier
Swift 7.1.01.0.0 or later (contract version 2)
Kotlin, Flutter and React Native 7.1.x1.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

SymptomLikely causeFix
Exit code 3No published policy for the projectSign and publish on the Policy tab, then start again
Exit code 1, and the policy fails validationTRUSTPIN_PROJECT_PUBLIC_KEY is not this project’s keyCopy it again from the bundle
Exit code 1, no policy source reachableOutbound HTTPS to the TrustPin CDNs is blockedAllow the outbound connections, or set HTTPS_PROXY
Exit code 1, schema behindThe Postgres tables are missing or older than the verifierApply attest-verifier migrations print
Exit code 2, “must be 1-128 characters” for TRUSTPIN_ORG_IDdocker run --env-file passed the quotes of an older bundle’s .env fileRemove the quotes, as in step 4
Exit code 2, “still the example placeholder”TRUSTPIN_MONITOR_API_KEY was uncommented without a valueSet a key from keygen --secret
Exit code 2, Play Integrity credentials missingEvidence is Play Integrity only or BothSet TRUSTPIN_PLAY_INTEGRITY_CREDENTIALS
check warns about the clockThe host clock is more than 30 s offSynchronise it with NTP
/v1/challenge answers 404 through the gatewayThe gateway forwards the URL’s path to the verifierStrip the path prefix
Port 9090 refuses connections from another container or podThe monitor port listens on 127.0.0.1 by defaultSet TRUSTPIN_MONITOR_LISTEN_ADDR=:9090 with TRUSTPIN_MONITOR_API_KEY
The app reports verifierUnavailableThe verifier’s domain isn’t registered, and the app pins strictlyRegister the domain

Next steps