Purchase Token Validation

Token handling overview

When your backend sends a purchase token to Tierux for verification, here's what happens:

1. Verification — Tierux calls the store API (Google Play Developer API or Apple certificate validation) to verify the token is genuine
2. Deduplication — the token is SHA-256 hashed; if the hash exists in the database, this is a duplicate and processing is skipped
3. Encryption — the raw token is encrypted with AES-256-GCM for later refresh operations
4. Normalization — the verified purchase is mapped to entitlement state

Raw purchase tokens are never stored on disk. Only the hash (for dedup) and the encrypted copy (for refresh) are persisted.

Token deduplication

Tierux uses SHA-256 hashing for deduplication. Two identical purchase tokens produce the same hash, so re-sending the same token for verification is a no-op — the existing entitlement state is returned.

// Dedup flow
purchaseToken → SHA-256(purchaseToken) → hash lookup
  → Found? Return existing entitlement state
  → Not found? Verify with store, then store hash + encrypted token

AES-256-GCM encryption

When a token refresh is needed, Tierux decrypts the stored encrypted copy using AES-256-GCM. The encryption key is configured via the PURCHASE_TOKEN_ENCRYPTION_KEY environment variable (minimum 16 characters).

# Required environment variable
PURCHASE_TOKEN_ENCRYPTION_KEY="your-secure-key-min-16-chars"

Each encryption operation uses a unique initialization vector (IV) for GCM, and the authentication tag ensures ciphertext integrity. Tokens are only decrypted transiently during refresh — never exposed in logs or responses.

Google Play token verification

Google Play tokens are verified via the androidpublisher.purchases.subscriptions.get API for subscriptions or androidpublisher.purchases.products.get for one-time products. Tierux extracts expiry time, auto-renew status, and cancellation state from the response.

Apple JWS verification

Apple StoreKit 2 transactions arrive as JWS tokens. Tierux verifies the JWS signature against Apple's root certificates, decodes the transaction payload, and normalizes it into the same entitlement state used for Google Play.