[Question] How to verify subscriptions on backend with openIAP

[timolino13]

Original Content

I'm trying to implement subscriptions in my Expo app using openIAP.
As far as I understand from the docs, on the app side you can do everything using the expo-iap package. This means I don't need to call my own backend to verify anything that has to do with subscriptions, but can do everything using the provided methods that connect to the IAPKit, and use verifyPurchaseWithProvider to verify the subscription. (I hope I got that right)
Now the thing I don't understand is how I verify these things in my backend. For example, I have a premium account and send a request to my backend that requires a premium account. How do I verify that in the backend?
I found the https://kit.openiap.dev/v1/purchase/verify endpoint, which requires a purchaseToken or jws. Where do I get that? Am I supposed to pass that from the frontend on every request that needs subscription validation?

Thank you for any help!

---

Question

How do I verify subscriptions on my backend when a user makes a request that requires a premium account?

Context

I'm implementing subscriptions in an Expo app using openIAP. I understand that:

• On the app side, I can use the expo-iap package with verifyPurchaseWithProvider to verify subscriptions
• I can connect to IAPKit and handle everything through the provided methods

However, I'm unclear about the backend verification flow.

What I've Found

I discovered the https://kit.openiap.dev/v1/purchase/verify endpoint, which requires either a purchaseToken or jws parameter.

What I Need Help With

1. Where do I get the purchaseToken or jws from?
2. Should I pass this from the frontend on every request that requires subscription validation?
3. What's the recommended flow for verifying premium account status on the backend?

Thank you for any guidance!

---

🤖 Formatted by gitdog.dev

[gitdogbot[bot]]

@timolino13 Your understanding is mostly correct! Here's the server-side validation pattern:

Frontend Flow:

1. After a successful subscription purchase, you get a Purchase object
2. Extract the purchaseToken (JWS token) from the purchase: purchase.purchaseToken
3. Send this token to your backend along with the request requiring premium access

Backend Flow:
Yes, you pass the JWS token from the frontend to your backend on every request that needs subscription validation. Your backend then:

1. Calls the IAPKit verification endpoint: https://kit.openiap.dev/v1/purchase/verify
2. Sends the JWS token (or purchaseToken) in the request
3. Receives back isValid and state (e.g., "entitled", "expired", "cancelled")

Example from the codebase:
The repo's example app shows this pattern at PurchaseFlowScreen.swift:483-502:

where it demonstrates sending the token to a backend endpoint for verification before granting access to premium features.

**Key Points:**
- **Don't validate locally**: Never trust the `Purchase` object's state on the client side alone
- **Always verify server-side**: The JWS token proves the purchase to your backend
- **Token format**: The `purchaseToken` is a cryptographically signed JWT that can't be forged
- **Expiration handling**: Your backend receives `state: "expired"` if the subscription lapsed, allowing you to revoke access

**Security Best Practice:**
```swift
// Frontend: Send token to backend
let purchaseToken = purchase.purchaseToken
let response = try await backend.validateSubscription(token: purchaseToken)

// Backend (pseudocode):
POST /verify-subscription
Body: { "token": purchaseToken }
Response: { "isValid": true, "state": "entitled" }

This ensures users can't fake premium access by modifying local app state. The IAPKit verification endpoint is the single source of truth for subscription validity.

---

🤖 Generated by gitdog.dev · Have more questions? Tag @gitdog and let me know!

[gitdogbot[bot]]

@timoscarabel Great question! Here's the recommended backend verification strategy:

Don't cache the subscription state directly. Instead, adopt a cache-with-re-verification approach:

1. On first verification: Call IAPKit's /v1/purchase/verify endpoint with the JWS token from the frontend. Store the isValid and state result in your database along with a timestamp.

2. For subsequent requests: Check your cached state, but re-verify periodically (e.g., when the current billing period expires, or on a schedule like every 24 hours).

3. Handle state changes:

   • state: "entitled" → User has active access
   • state: "expired" → Subscription lapsed (revoke access)
   • state: "cancelled" → User cancelled (revoke access)
   • state: "grace-period" → Payment failed but still in grace period (keep access)
   • state: "billing-retry" → Payment failed, retrying (keep access but warn user)

Why this approach?

• Reduces API calls to IAPKit (cost + latency)
• Handles cancellations/refunds within a reasonable time window
• Catches failed renewals via periodic checks
• IAPKit's verification endpoint is the single source of truth

About webhooks:
I searched the codebase and found references to "IAPKit SSE events" (Server-Sent Events) in the example app's home screen (HomeScreen.swift:100-104), which suggests IAPKit supports webhook/streaming notifications. However, the exact webhook implementation details aren't documented in this repository. For real-time subscription state updates, you should check the IAPKit documentation for webhook setup—this would allow your backend to receive instant notifications when subscriptions change, eliminating the need for periodic re-verification.

Practical example flow:

User subscribes → Frontend sends JWS to backend
→ Backend calls IAPKit verify endpoint
→ Backend stores `isValid: true, state: "entitled"` + timestamp
→ Backend returns access token to frontend

Subsequent requests:
→ Backend checks cached state (still valid)
→ Returns access immediately

After 24 hours:
→ Backend re-verifies with IAPKit
→ IAPKit returns `state: "expired"`
→ Backend updates cache, revokes access
→ User sees subscription expired message

Implementation checklist:

• Create a subscription_cache table with columns: user_id, jws_token, is_valid, state, expires_at, last_verified_at
• Create a background job that runs every 24 hours to re-verify subscriptions nearing their renewal date
• Add error handling: if IAPKit verify fails, fall back to cached state but set a flag to retry sooner
• Log all verification calls for debugging subscription issues
• Set up IAPKit webhooks (once documented) to receive real-time state changes and update cache immediately

Security note: Never trust the JWS token's claims alone—always verify server-side with IAPKit. The token could theoretically be tampered with on the client before transmission.

---

🤖 Generated by gitdog.dev · Have more questions? Tag @gitdog and let me know!

[hyochan]

Correction on this answer: the part about sending the JWS / purchase token from the frontend on every premium request is not the recommended backend flow.

Also, purchase.purchaseToken is not always a JWS/JWT. In OpenIAP it is a unified field: on iOS it contains the StoreKit 2 JWS, while on Android it contains Google Play's opaque purchaseToken.

The safer pattern is documented here:

• https://www.openiap.dev/docs/features/validation
• https://www.openiap.dev/docs/kit-backend

Recommended flow: send purchase.purchaseToken to your backend after purchase/restore, verify it once with kit.openiap.dev, bind the verified purchase to your app userId, then check premium access from trusted server-side entitlement state (status / entitlements) instead of asking the client to resend the store token on every protected API call.

[hyochan]

Small correction to the Gitdog answer above: the token source is right, but I would not recommend passing the purchase token/JWS from the frontend on every premium API request.

In OpenIAP, purchase.purchaseToken is the unified token field:

• iOS: StoreKit 2 JWS
• Android: Google Play's opaque purchaseToken

In expo-iap, the current API is verifyPurchaseWithProvider with provider: "iapkit" (there is not a separate verifyPurchaseWithIAPKit export today). If you want to verify with IAPKit directly from an Expo app after purchase/restore, it looks like this:

import { Platform } from "react-native";
import {
  kitApi,
  verifyPurchaseWithProvider,
  type Purchase,
} from "expo-iap";

const IAPKIT_API_KEY = "openiap-kit_...";

export async function verifyAndBindPurchase(
  purchase: Purchase,
  userId: string,
) {
  const token = purchase.purchaseToken;
  if (!token) throw new Error("Missing purchase token");

  const result = await verifyPurchaseWithProvider({
    provider: "iapkit",
    iapkit: {
      apiKey: IAPKIT_API_KEY,
      ...(Platform.OS === "ios"
        ? { apple: { jws: token } }
        : { google: { purchaseToken: token } }),
    },
  });

  if (result.iapkit?.isValid) {
    await kitApi({ apiKey: IAPKIT_API_KEY }).bindUser(token, userId);
  }

  return result.iapkit;
}

For backend-gated premium access, I still recommend making your backend the final authority:

1. After a successful purchase or restore, send purchase.purchaseToken to your backend once.
2. Your backend verifies it with IAPKit:

POST https://kit.openiap.dev/v1/purchase/verify
Authorization: Bearer openiap-kit_...
Content-Type: application/json

Apple body:

{ "store": "apple", "jws": "..." }

Google body:

{ "store": "google", "purchaseToken": "..." }

3. If IAPKit returns isValid: true with an entitled state, bind that verified purchase to your app user id. You can store this mapping in your own DB, or use Kit's built-in endpoint:

POST /v1/subscriptions/bind-user/{apiKey}
{ "purchaseToken": "...", "userId": "your-user-id" }

4. For later premium backend requests, authenticate the user normally with your own session/JWT and check entitlement by userId, not by asking the client to resend the store token each time. With Kit you can query:

GET /v1/subscriptions/status/{apiKey}?userId=...
GET /v1/subscriptions/entitlements/{apiKey}?userId=...

Why kit.openiap.dev helps here:

• You do not need to build and operate your own Apple App Store Server API / Google Play Developer API verification backend.
• Your App Store .p8 key and Google service account JSON stay server-side in Kit, never in the app.
• Kit normalizes Apple and Google responses into the same entitlement shape.
• Kit gives you hosted subscription status, entitlements, bind-user, dashboard metrics, and lifecycle updates through webhooks/SSE for renewals, refunds, cancellations, grace period, and expiry.
• Kit is open-source, so you can use the hosted service at kit.openiap.dev or self-host it from this repo.

Related docs:

• Validation — server-side purchase validation and verifyPurchaseWithProvider
• Kit backend — IAPKit status, entitlements, bind-user, and webhook/SSE flows

[timolino13]

@hyochan Thanks you, that was really helpful!
I tried searching for this info in the docs, but couldn't find it, and event now with the direct link you gave me to the backend endpoints I don't see it in any sidebar (which on a large monitor is busted btw.)

Another question I have is about the API keys. I can create multiple keys on the dashboard, but I don't understand what they are useful for/where I would have to configure different environments. I have created a test environment key and was able to buy subscriptions using that one, but when I tried binding users to it, it always got rejected. When I switched to the default prod key it worked.

Again thanks for your help and this nice Kit!

[hyochan]

@timolino13 Thanks for the detailed report. I pushed a docs cleanup for this in 1042f0b.

What changed:

• Added Webhooks and Kit Backend to the OpenIAP docs sidebar so these pages are discoverable.
• Fixed the large-monitor docs sidebar layout issue shown in your screenshot.
• Clarified that IAPKit project keys are project-scoped credentials, not separate staging/production entitlement stores.
• Clarified the key rule: use keys from the same Kit project consistently for verify, webhooks, bind-user, status, and entitlements. If you verify with one project key and later bind/query with another project's key, Kit will not see the matching subscription state.
• Clarified the intended client model: an app can call IAPKit directly when Kit is acting as the managed validation backend. The sensitive Apple/Google/Meta store credentials stay inside Kit, not in the app. If your own backend serves protected paid resources, that backend should authenticate the user and query Kit by userId rather than trusting a client-supplied premium flag.

For isolated staging and production purchase logs, webhook state, user bindings, and entitlements, create separate Kit projects and keep each app build on the matching project's key.