insforge-integrations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

InsForge Integrations

InsForge 集成

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.

本Skill涵盖将第三方提供商与InsForge集成的内容。目前支持两类提供商：认证提供商（通过JWT声明实现RLS）和支付服务商（x402 HTTP支付协议）。每个提供商在本目录下都有对应的指南。

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

提供商	指南	使用场景
Clerk	Clerk JWT 模板 + InsForge RLS	Clerk通过JWT模板直接签署令牌——无需服务端签署
Auth0	Auth0 Actions + InsForge RLS	Auth0使用登录后Action将声明嵌入访问令牌
WorkOS	WorkOS AuthKit + InsForge RLS	WorkOS AuthKit中间件 + 使用 `jsonwebtoken` 进行服务端JWT签署
Kinde	Kinde + InsForge RLS	针对InsForge集成的Kinde令牌自定义
Stytch	Stytch + InsForge RLS	用于InsForge集成的Stytch会话令牌

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

提供商	指南	使用场景
OKX x402	OKX 作为x402服务商（X Layer上的USDG）	链上按使用付费的HTTP端点，付款方无需支付Gas费

Common Patterns

通用模式

Auth providers

认证提供商

Provider signs or issues a JWT containing the user's ID
JWT is passed to InsForge via
```
edgeFunctionToken
```
in
```
createClient()
```
InsForge extracts claims via
```
request.jwt.claims
```
in SQL
RLS policies use a
```
requesting_user_id()
```
function to enforce row-level security

提供商签署或颁发包含用户ID的JWT
通过
createClient()
中的
edgeFunctionToken
将JWT传递给InsForge
InsForge通过SQL中的
request.jwt.claims
提取声明
RLS策略使用
requesting_user_id()
函数强制执行行级安全

Payment facilitators (x402)

支付服务商（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

服务端返回
402 Payment Required
响应，其中JSON挑战以Base64编码形式放在
PAYMENT-REQUIRED
请求头中
客户端使用稳定币的EIP-712域签署EIP-3009授权
服务端将签署后的负载转发至服务商的
/verify
和
/settle
端点
服务端将已结算的支付记录到InsForge表中，并通过实时触发器更新实时仪表盘

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

Payment facilitators

OKX x402 — Onchain pay-per-use via USDG on X Layer; zero gas for the payer

认证

Clerk — 设置最简单；JWT模板处理签署，无需服务端代码
Auth0 — 灵活性高；使用登录后Action注入声明
WorkOS — 面向企业；AuthKit中间件 + 服务端JWT签署
Kinde — 开发者友好；内置令牌自定义功能
Stytch — API优先；基于会话的令牌流程

支付服务商

OKX x402 — 通过X Layer上的USDG实现链上按使用付费；付款方无需支付Gas费

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.

每个提供商指南都包含完整的代码示例，涵盖：

提供商仪表盘配置（API密钥、应用设置等）
服务端和客户端代码（认证用的JWT工具；支付用的服务商客户端 + 签署工具）
数据库设置（认证用的RLS；支付用的支付表 + 实时触发器）
环境变量设置

请参考具体的

references/<provider>.md

文件获取完整示例。

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
Set
```
edgeFunctionToken
```
as an async function (Clerk) or server-signed JWT (Auth0, WorkOS, Kinde, Stytch)

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
```
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

认证

所有认证提供商的用户ID均为字符串（非UUID）——
```
user_id
```
列请始终使用
```
TEXT
```
类型
RLS策略中使用
```
requesting_user_id()
```
而非
```
auth.uid()
```
将
```
edgeFunctionToken
```
设置为异步函数（Clerk）或服务端签署的JWT（Auth0、WorkOS、Kinde、Stytch）

始终通过

npx @insforge/cli secrets get JWT_SECRET

获取JWT密钥

支付服务商（x402）

结算完成后务必检查数据库
```
insert(...)
```
的结果——结算会先在链上扣款，再执行插入操作；若数据库静默失败会丢失记录
为
```
tx_hash
```
列添加
```
UNIQUE
```
约束，防止重试产生重复记录
验证EIP-712域（
```
name
```
、
```
version
```
）与令牌合约链上的
```
DOMAIN_SEPARATOR
```
是否一致——错误值会导致
```
Invalid Authority
```
错误
本地开发时使用
```
MOCK_OKX_FACILITATOR
```
环境变量，这样无需真实资金即可测试完整流程

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

认证

错误	解决方案
RLS中使用 `auth.uid()`	使用 `requesting_user_id()` ——第三方ID为字符串，而非UUID
`user_id` 列使用UUID类型	使用 `TEXT` 类型——所有支持的提供商均使用字符串格式的ID
硬编码JWT密钥	始终通过 `npx @insforge/cli secrets get JWT_SECRET` 获取
缺少 `requesting_user_id()` 函数	必须先创建该函数，RLS策略才能生效

支付（x402）

错误	解决方案
使用OKX交易所交易API密钥	在 `web3.okx.com/onchainos/dev-portal` 创建独立的Web3 API密钥
EIP-712域值错误	读取令牌合约的 `DOMAIN_SEPARATOR` ——X Layer上的USDG需使用 `name: "Global Dollar"` 、 `version: "1"`
忽略结算后的数据库插入错误	务必解构 `{ error }` 并记录/处理错误——资金已完成划转
生产环境中设置 `MOCK_OKX_FACILITATOR=true`	模拟模式仅用于演示；它会返回虚假交易哈希并跳过验证