OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add insforge/insforge-skills --skill insforge-integrations
Use when wiring an external auth provider (Clerk, Auth0, WorkOS, Kinde, Stytch, Better Auth) into InsForge for JWT-based RLS, or when adding the OKX x402 payment facilitator for onchain pay-per-use billing.
npx skills add insforge/insforge-skills --skill 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.
| 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 |
| 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 |
accessToken in createClient() (deprecated alias: edgeFunctionToken)auth.jwt() in SQLrequesting_user_id() function to enforce row-level security402 Payment Required with a JSON challenge base64-encoded in PAYMENT-REQUIRED header/verify + /settle endpointsAuth
REVOKE after migrate to seal PostgREST exposure.Payment facilitators
Each provider guide includes full code examples for:
Refer to the specific references/<provider>.md file for complete examples.
Auth
TEXT columns for user_idrequesting_user_id() instead of auth.uid() for RLS policiesaccessToken — a static string, not a function; for short-lived tokens (Clerk) sync refreshes with client.setAccessToken(token, AuthChangeEvent.TOKEN_REFRESHED) after the initial same-user sign-innpx -y @insforge/cli secrets get JWT_SECRETPayment facilitators (x402)
insert(...) after settlement — settlement takes money onchain before the insert runs; a silent DB failure loses the recordUNIQUE to the tx_hash column to prevent duplicate records from retriesname, version) against the token contract's on-chain DOMAIN_SEPARATOR — wrong values produce Invalid Authority errorsMOCK_OKX_FACILITATOR env flag for local dev so the full flow can be exercised without real fundsAuth
| 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 -y @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 |