om-scogo InsForge Integrations
This 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.
Auth Providers
| Provider | Guide | When to use |
|---|---|---|
| Clerk | Clerk JWT Templates + InsForge RLS | Clerk signs tokens directly via JWT Template — no server-side signing needed |
| Auth0 | Auth0 Actions + InsForge RLS | Auth0 uses a post-login Action to embed claims into the access token |
| WorkOS | WorkOS AuthKit + InsForge RLS | WorkOS AuthKit middleware + server-side JWT signing with jsonwebtoken |
| Kinde | Kinde + InsForge RLS | Kinde token customization for InsForge integration |
| Stytch | Stytch + InsForge RLS | Stytch session tokens for InsForge integration |
| Better Auth | Better Auth + InsForge RLS | Self-hosted auth running in your InsForge Postgres — no third-party SaaS, no per-MAU cost |
Payment Facilitators
| Provider | Guide | When to use |
|---|---|---|
| OKX x402 | OKX as x402 facilitator (USDG on X Layer) | Pay-per-use HTTP endpoints settled onchain with zero gas for the payer |
Common Patterns
Auth providers
- Provider signs or issues a JWT containing the user's ID
- JWT is passed to InsForge via
accessTokenincreateClient()(deprecated alias:edgeFunctionToken) - InsForge exposes claims through
auth.jwt()in SQL - RLS policies use a
requesting_user_id()function to enforce row-level security
Payment facilitators (x402)
- Server returns
402 Payment Requiredwith a JSON challenge base64-encoded inPAYMENT-REQUIREDheader - Client signs an EIP-3009 authorization using the stablecoin's EIP-712 domain
- Server forwards the signed payload to the facilitator's
/verify+/settleendpoints - Server records the settled payment in an InsForge table with a realtime trigger for live dashboards
Choosing a Provider
Auth
- Clerk — Simplest setup; JWT Template handles signing, no server code needed
- Auth0 — Flexible; uses post-login Actions for claim injection
- WorkOS — Enterprise-focused; AuthKit middleware + server-side JWT signing
- Kinde — Developer-friendly; built-in token customization
- Stytch — API-first; session-based token flow
- Better Auth — Self-hosted in your Postgres; no SaaS vendor; you own the user table. Pairs cleanly with InsForge's Postgres via a connection string + a small bridge route. Requires a one-time
REVOKEafter migrate to seal PostgREST exposure.
Payment facilitators
- OKX x402 — Onchain pay-per-use via USDG on X Layer; zero gas for the payer
Setup
- Identify which provider the project uses
- Read the corresponding reference guide from the tables above
- Follow the provider-specific setup steps
Usage Examples
Each provider guide includes full code examples for:
- Provider dashboard configuration (API keys, application settings, etc.)
- Server and client code (JWT utilities for auth; facilitator client + signing utilities for payments)
- Database setup (RLS for auth; payment table + realtime trigger for payments)
- Environment variable setup
Refer to the specific references/<provider>.md file for complete examples.
Best Practices
Auth
- All auth provider user IDs are strings (not UUIDs) — always use
TEXTcolumns foruser_id - Use
requesting_user_id()instead ofauth.uid()for RLS policies - Pass the JWT via
accessToken— a static string, not a function; for short-lived tokens (Clerk) sync refreshes withclient.setAccessToken(token, AuthChangeEvent.TOKEN_REFRESHED)after the initial same-user sign-in - Always get the JWT secret via
npx @insforge/cli secrets get JWT_SECRET
Payment facilitators (x402)
- Always check the result of the database
insert(...)after settlement — settlement takes money onchain before the insert runs; a silent DB failure loses the record - Add
UNIQUEto thetx_hashcolumn to prevent duplicate records from retries - Verify EIP-712 domain (
name,version) against the token contract's on-chainDOMAIN_SEPARATOR— wrong values produceInvalid Authorityerrors - Use a
MOCK_OKX_FACILITATORenv flag for local dev so the full flow can be exercised without real funds
Common Mistakes
Auth
| Mistake | Solution |
|---|---|
Using auth.uid() for RLS |
Use requesting_user_id() — third-party IDs are strings, not UUIDs |
Using UUID columns for user_id |
Use TEXT — all supported providers use string-format IDs |
| Hardcoding the JWT secret | Always retrieve via npx @insforge/cli secrets get JWT_SECRET |
Missing requesting_user_id() function |
Must be created before RLS policies will work |
Payments (x402)
| Mistake | Solution |
|---|---|
| Using an OKX exchange trading API key | Create a separate Web3 API key at web3.okx.com/onchainos/dev-portal |
| Wrong EIP-712 domain values | Read the token contract's DOMAIN_SEPARATOR — for USDG on X Layer use name: "Global Dollar", version: "1" |
| Ignoring DB insert error after settlement | Always destructure { error } and log/handle it — money has already moved |
MOCK_OKX_FACILITATOR=true in production |
Mock mode is demo-only; it returns fake tx hashes and bypasses verification |