InsForgeInsForge/insforge-skills/skills/insforge-integrations/SKILL.md

insforge-integrations

Skill47 starsChanged 5 months agoApache-2.0View on GitHub

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.

In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- insforge-cliSkill
- insforge-debugSkill
- insforgeSkill

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 2 are distinctive, and 8 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
RLS policies: use a requesting_user_id() function to enforce row-level security
line 37
Distinctive:
Read the corresponding reference guide from the tables above
line 61
Distinctive:
Follow the provider-specific setup steps
line 62
Very specific:
All auth provider user IDs are strings (not UUIDs) — always use TEXT columns for user_id
line 77
Very specific:
Use requesting_user_id() instead of auth.uid() for RLS policies
line 78
Very specific:
Always get the JWT secret via npx -y @insforge/cli secrets get JWT_SECRET
line 80
Very specific:
Always check the result of the database insert(...) after settlement — settlement takes money onchain before the insert runs.
line 83
Very specific:
Add UNIQUE to the tx_hash column to prevent duplicate records from retries
line 84
Very specific:
Verify EIP-712 domain (name, version) against the token contract's on-chain DOMAIN_SEPARATOR — wrong values produce Invalid Authority errors
line 85
Very specific:
Use a MOCK_OKX_FACILITATOR env flag for local dev so the full flow can be exercised without real funds
line 86

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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 accessToken in createClient() (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 Required with a JSON challenge base64-encoded in PAYMENT-REQUIRED header
Client signs an EIP-3009 authorization using the stablecoin's EIP-712 domain
Server forwards the signed payload to the facilitator's /verify + /settle endpoints
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 REVOKE after 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 TEXT columns for user_id
Use requesting_user_id() instead of auth.uid() for RLS policies
Pass the JWT via accessToken — 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-in
Always get the JWT secret via npx -y @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 UNIQUE to the tx_hash column to prevent duplicate records from retries
Verify EIP-712 domain (name, version) against the token contract's on-chain DOMAIN_SEPARATOR — wrong values produce Invalid Authority errors
Use a MOCK_OKX_FACILITATOR env 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 -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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free