Insforge Integrations

1---2name: insforge-integrations3description: >-4  Use this skill when integrating a third-party provider with InsForge —5  either an auth provider (Clerk, Auth0, WorkOS, Kinde, Stytch) for JWT-based6  RLS, or a payment facilitator (OKX x402) for onchain pay-per-use billing.7  Covers provider-specific dashboard setup, client/server code, database8  policies, and common gotchas for each supported integration.9license: Apache-2.010metadata:11  author: insforge12  version: "1.1.0"13  organization: InsForge14  date: April 202615---16 17# InsForge Integrations18 19This skill covers integrating **third-party providers** with InsForge. Currently two categories are supported: **auth providers** (RLS via JWT claims) and **payment facilitators** (x402 HTTP payment protocol). Each provider has its own guide under this directory.20 21## Auth Providers22 23| Provider | Guide | When to use |24|----------|-------|-------------|25| [Clerk](references/clerk.md) | Clerk JWT Templates + InsForge RLS | Clerk signs tokens directly via JWT Template — no server-side signing needed |26| [Auth0](references/auth0.md) | Auth0 Actions + InsForge RLS | Auth0 uses a post-login Action to embed claims into the access token |27| [WorkOS](references/workos.md) | WorkOS AuthKit + InsForge RLS | WorkOS AuthKit middleware + server-side JWT signing with `jsonwebtoken` |28| [Kinde](references/kinde.md) | Kinde + InsForge RLS | Kinde token customization for InsForge integration |29| [Stytch](references/stytch.md) | Stytch + InsForge RLS | Stytch session tokens for InsForge integration |30 31## Payment Facilitators32 33| Provider | Guide | When to use |34|----------|-------|-------------|35| [OKX x402](references/okx-x402.md) | OKX as x402 facilitator (USDG on X Layer) | Pay-per-use HTTP endpoints settled onchain with zero gas for the payer |36 37## Common Patterns38 39### Auth providers401. **Provider signs or issues a JWT** containing the user's ID412. **JWT is passed to InsForge** via `edgeFunctionToken` in `createClient()`423. **InsForge extracts claims** via `request.jwt.claims` in SQL434. **RLS policies** use a `requesting_user_id()` function to enforce row-level security44 45### Payment facilitators (x402)461. **Server returns `402 Payment Required`** with a JSON challenge base64-encoded in `PAYMENT-REQUIRED` header472. **Client signs an EIP-3009 authorization** using the stablecoin's EIP-712 domain483. **Server forwards the signed payload** to the facilitator's `/verify` + `/settle` endpoints494. **Server records the settled payment** in an InsForge table with a realtime trigger for live dashboards50 51## Choosing a Provider52 53**Auth**54- **Clerk** — Simplest setup; JWT Template handles signing, no server code needed55- **Auth0** — Flexible; uses post-login Actions for claim injection56- **WorkOS** — Enterprise-focused; AuthKit middleware + server-side JWT signing57- **Kinde** — Developer-friendly; built-in token customization58- **Stytch** — API-first; session-based token flow59 60**Payment facilitators**61- **OKX x402** — Onchain pay-per-use via USDG on X Layer; zero gas for the payer62 63## Setup64 651. Identify which provider the project uses662. Read the corresponding reference guide from the tables above673. Follow the provider-specific setup steps68 69## Usage Examples70 71Each provider guide includes full code examples for:72- Provider dashboard configuration (API keys, application settings, etc.)73- Server and client code (JWT utilities for auth; facilitator client + signing utilities for payments)74- Database setup (RLS for auth; payment table + realtime trigger for payments)75- Environment variable setup76 77Refer to the specific `references/<provider>.md` file for complete examples.78 79## Best Practices80 81**Auth**82- All auth provider user IDs are strings (not UUIDs) — always use `TEXT` columns for `user_id`83- Use `requesting_user_id()` instead of `auth.uid()` for RLS policies84- Set `edgeFunctionToken` as an async function (Clerk) or server-signed JWT (Auth0, WorkOS, Kinde, Stytch)85- Always get the JWT secret via `npx @insforge/cli secrets get JWT_SECRET`86 87**Payment facilitators (x402)**88- Always check the result of the database `insert(...)` after settlement — settlement takes money onchain before the insert runs; a silent DB failure loses the record89- Add `UNIQUE` to the `tx_hash` column to prevent duplicate records from retries90- Verify EIP-712 domain (`name`, `version`) against the token contract's on-chain `DOMAIN_SEPARATOR` — wrong values produce `Invalid Authority` errors91- Use a `MOCK_OKX_FACILITATOR` env flag for local dev so the full flow can be exercised without real funds92 93## Common Mistakes94 95**Auth**96 97| Mistake | Solution |98|---------|----------|99| Using `auth.uid()` for RLS | Use `requesting_user_id()` — third-party IDs are strings, not UUIDs |100| Using UUID columns for `user_id` | Use `TEXT` — all supported providers use string-format IDs |101| Hardcoding the JWT secret | Always retrieve via `npx @insforge/cli secrets get JWT_SECRET` |102| Missing `requesting_user_id()` function | Must be created before RLS policies will work |103 104**Payments (x402)**105 106| Mistake | Solution |107|---------|----------|108| Using an OKX exchange trading API key | Create a separate Web3 API key at `web3.okx.com/onchainos/dev-portal` |109| Wrong EIP-712 domain values | Read the token contract's `DOMAIN_SEPARATOR` — for USDG on X Layer use `name: "Global Dollar"`, `version: "1"` |110| Ignoring DB insert error after settlement | Always destructure `{ error }` and log/handle it — money has already moved |111| `MOCK_OKX_FACILITATOR=true` in production | Mock mode is demo-only; it returns fake tx hashes and bypasses verification |