Verifying tokens in your API

For backend and API developers. At the end of this page, your API verifies the attestation header and decides what a request without a valid token may do.

Requests from attested apps carry one header:

TrustPin-Attestation: <token>

The token is a JWT signed by your verifier with ES256. Your API, or your gateway, verifies it like any other JWT issued by a trusted issuer, then applies the attestation claims.

Token format

Header: alg: ES256, typ: trustpin-attest+jwt, kid naming one of the verifier’s signing keys.

{
  "iss": "<TRUSTPIN_TOKEN_ISSUER>",
  "aud": "<TRUSTPIN_TOKEN_AUDIENCE>",
  "sub": "<device key id>",
  "iat": 1792400000,
  "exp": 1792403600,
  "jti": "<random>",
  "bind": "<base64url(SHA-256(bound value))>",
  "tp": {
    "prj": "tprn::project::<organization id>::<project id>",
    "plat": "apple",
    "app": "ABCDE12345.com.example.app",
    "ev": ["app_attest"],
    "env": "production",
    "pv": 7,
    "mode": "enforce",
    "result": "pass",
    "reasons": []
  }
}

Verification steps

1. Fetch and cache GET <verifier>/.well-known/jwks.json. Refetch when a token carries an unknown kid, at most once every 30 s, with a 5 s fetch timeout.
2. Reject any alg other than ES256 and any typ other than trustpin-attest+jwt. The type check also rejects key certificates.
3. Check the signature against the JWKS key named by kid.
4. Check iss, aud and exp, allowing at most 60 seconds of clock skew, and that tp.prj equals tprn::project::<organization id>::<project id>. Refuse a token without it.
5. If you use binding: require bind and compare it with base64url(SHA-256(<the agreed value>)), unpadded, over the header value exactly as received. With the SDKs’ bindToHeader("Authorization"), the agreed value is the request’s Authorization header. With Require token binding on, turn on the require-binding option so a token without bind is refused.
6. Reject tp.env == "debug" outside development environments.
7. Apply the mode rules below.

Gateways that locate keys through OIDC discovery can use <verifier>/.well-known/openid-configuration when the verifier’s TRUSTPIN_TOKEN_ISSUER is its public https:// URL. Built-in JWT authorizers can’t check typ, tp.prj, debug tokens or binding; see Checking tokens at the gateway.

Monitor and enforce

Forged evidence never yields a token, and an app the policy doesn’t list gets 403 app_not_allowed in both modes.

Requests without the header

The SDKs never block the app’s own requests, so a request without the header is your decision, per endpoint. These requests come from old app versions, unsupported devices, attestation failures, and requests still waiting on a token. Common choices are to refuse sensitive operations, rate-limit harder, or flag the session.

Assertions for sensitive operations

From SDK 7.1.0 and verifier contract version 2, an app can send, next to the token, an assertion bound to one operation:

TrustPin-Attestation: <token>
TrustPin-Assertion: <base64url(clientData)>.<base64url(signature)>

The client data names a single-use nonce the SDK fetched from your verifier, the app’s SHA-256 digest of the operation (payload), and the token’s binding. Your API decides which endpoints require it. To verify one, compute your own digest of the same bytes the app digested (for example the request body) and call the verifier:

POST <verifier>/v1/assertion
Content-Type: application/json
 
{ "token": "<TrustPin-Attestation value>", "assertion": "<TrustPin-Assertion value>", "payload": "<base64url(SHA-256 digest)>" }

A 200 returns the token’s claims with the verified assertion; anything else (403 attestation_failed with assertion_invalid, payload_mismatch, key_mismatch or counter_invalid; 401 invalid_challenge for an expired or reused nonce) means the operation must be refused. The verifier checks the token itself, so the API need not verify it separately for that request. Access tokens carry the device public key (cnf) from contract version 2 for this purpose; APIs that do not verify assertions ignore it.

Example (Node.js, jose)

This is the verifier’s tested example, on jose 6.x:

import { createHash } from "node:crypto";
import { createRemoteJWKSet, jwtVerify } from "jose";
 
// project: the expected tp.prj (tprn::project::<organizationId>::<projectId>);
//   omitted, it is the audience when the audience has that form (the default),
//   otherwise there is no project check.
// requireBind: refuse tokens without `bind` (policy tokens.binding: required).
export function makeVerifier({ jwksUrl, issuer, audience, project, requireBind = false }) {
  const expectedProject = project || (audience.startsWith("tprn::project::") ? audience : "");
  // Caches the keys for 5 minutes and refetches on an unknown kid at most
  // once per 30 s (an unknown kid inside the cooldown is refused without a
  // fetch); concurrent misses share one fetch, which gives up after 5 s.
  const jwks = createRemoteJWKSet(new URL(jwksUrl), {
    cacheMaxAge: 300_000,
    cooldownDuration: 30_000,
    timeoutDuration: 5_000,
  });
  return async function verify(token, authorization) {
    const { payload } = await jwtVerify(token, jwks, {
      algorithms: ["ES256"],
      typ: "trustpin-attest+jwt",
      issuer,
      audience,
      clockTolerance: 60,
      requiredClaims: ["exp"],
    });
    if (expectedProject && payload.tp?.prj !== expectedProject) throw new Error("wrong project");
    if (payload.tp?.env === "debug") throw new Error("debug token");
    if (payload.bind === undefined && requireBind) throw new Error("unbound token");
    if (payload.bind !== undefined) {
      const expected = createHash("sha256").update(authorization).digest("base64url");
      if (payload.bind !== expected) throw new Error("bound to another session");
    }
    return payload;
  };
}

The same rules are available as downloads for Go, Node.js, Python and Java.

These samples may be copied and modified freely, under the verifier licence’s Code Samples clause.

Troubleshooting

Next steps

• Checking tokens at the gateway
• Rolling out: monitor to enforce