# Insforge Integrations

> Úsalo para conectar un proveedor de autenticación externo (Clerk, Auth0, WorkOS, Kinde, Stytch, Better Auth) a InsForge para RLS basado en JWT, o para añadir el facilitador de pagos OKX x402 para cobros on-chain por uso.

Fuente: https://skillsagentes.com/skills/insforge/insforge-skills/insforge-integrations
Markdown: https://skillsagentes.com/skills/insforge/insforge-skills/insforge-integrations.md

Repositorio: https://github.com/InsForge/insforge-skills
Autor: InsForge
Licencia: Apache-2.0
Actualizado: hace 20 días
Coste de contexto: 52 tok instalada, 1.5k tok al activarse, 28.4k tok con todos los archivos del bundle
Bundle: 9 archivos, 111 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add InsForge/insforge-skills --skill insforge-integrations --agent claude-code
# Cursor
npx -y skills add InsForge/insforge-skills --skill insforge-integrations --agent cursor
# Codex
npx -y skills add InsForge/insforge-skills --skill insforge-integrations --agent codex
# Gemini CLI
npx -y skills add InsForge/insforge-skills --skill insforge-integrations --agent gemini
# Windsurf
npx -y skills add InsForge/insforge-skills --skill insforge-integrations --agent windsurf
# Cline
npx -y skills add InsForge/insforge-skills --skill insforge-integrations --agent cline
```

## Qué hace

- Guía la integración de proveedores de auth externos (Clerk, Auth0, WorkOS, Kinde, Stytch, Better Auth) con InsForge mediante JWT y RLS
- Explica el patrón común: el proveedor firma un JWT, se pasa a InsForge vía `accessToken` y las políticas RLS usan `requesting_user_id()`
- Cubre el facilitador de pagos OKX x402 para cobros on-chain por uso, con verificación EIP-3009/EIP-712
- Remite a la guía específica de cada proveedor en `references/<provider>.md` con ejemplos completos de código

## Cuándo usarla

- Hay que conectar un proveedor de auth (Clerk, Auth0, WorkOS, Kinde, Stytch, Better Auth) a InsForge para usar RLS por JWT
- Hay que añadir cobros on-chain por uso con el facilitador de pagos OKX x402

## Qué la activa

- "Conecta Clerk con InsForge para autenticación"
- "Configura RLS con JWT usando Auth0 en InsForge"
- "Añade pagos on-chain con OKX x402"

## Antes de instalar

- Necesita el secreto `JWT_SECRET` del proyecto InsForge (vía `npx -y @insforge/cli secrets get JWT_SECRET`) y las credenciales del proveedor elegido.

## Archivos

- SKILL.md — 6 KB
- agents/openai.yaml — 235 B
- references/auth0.md — 6 KB
- references/better-auth.md — 34 KB
- references/clerk.md — 9 KB
- references/kinde.md — 5 KB
- references/okx-x402.md — 38 KB
- references/stytch.md — 8 KB
- references/workos.md — 5 KB

## SKILL.md

Reproducido tal cual desde InsForge/insforge-skills bajo Apache-2.0. Esta sección es el documento original y está en inglés.

# 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](references/clerk.md) | Clerk JWT Templates + InsForge RLS | Clerk signs tokens directly via JWT Template — no server-side signing needed |
| [Auth0](references/auth0.md) | Auth0 Actions + InsForge RLS | Auth0 uses a post-login Action to embed claims into the access token |
| [WorkOS](references/workos.md) | WorkOS AuthKit + InsForge RLS | WorkOS AuthKit middleware + server-side JWT signing with `jsonwebtoken` |
| [Kinde](references/kinde.md) | Kinde + InsForge RLS | Kinde token customization for InsForge integration |
| [Stytch](references/stytch.md) | Stytch + InsForge RLS | Stytch session tokens for InsForge integration |
| [Better Auth](references/better-auth.md) | 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](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 |

## Common Patterns

### Auth providers
1. **Provider signs or issues a JWT** containing the user's ID
2. **JWT is passed to InsForge** via `accessToken` in `createClient()` (deprecated alias: `edgeFunctionToken`)
3. **InsForge exposes claims** through `auth.jwt()` in SQL
4. **RLS policies** use a `requesting_user_id()` function to enforce row-level security

### Payment facilitators (x402)
1. **Server returns `402 Payment Required`** with a JSON challenge base64-encoded in `PAYMENT-REQUIRED` header
2. **Client signs an EIP-3009 authorization** using the stablecoin's EIP-712 domain
3. **Server forwards the signed payload** to the facilitator's `/verify` + `/settle` endpoints
4. **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

1. Identify which provider the project uses
2. Read the corresponding reference guide from the tables above
3. 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 |

## Dónde encaja

- Categoría: [Desarrollo de APIs](https://skillsagentes.com/categorias/desarrollo-apis.md) — Diseña, prueba y documenta APIs HTTP y GraphQL.
- Creador: [InsForge](https://skillsagentes.com/creators/insforge.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Insforge Cli](https://skillsagentes.com/skills/insforge/insforge-skills/insforge-cli.md): Úsalo siempre que se necesite un backend, o cuando una tarea toque la infraestructura o nube de InsForge mediante el CLI: proyectos, SQL, migraciones, RLS, funciones, storage, backups, despliegues, secretos, cron, logs, advisor y más.
- [Insforge](https://skillsagentes.com/skills/insforge/insforge-skills/insforge.md): Úsalo al escribir código de app con InsForge o @insforge/sdk: CRUD de base de datos, auth, storage, funciones, IA de OpenRouter, tiempo real, emails, pagos con Stripe o Razorpay, o herramientas S3 apuntando al Storage de InsForge.
- [Insforge Debug](https://skillsagentes.com/skills/insforge/insforge-skills/insforge-debug.md): Úsalo para diagnosticar problemas en InsForge: fallos reactivos (errores del SDK, HTTP 4xx/5xx, timeouts, login/OAuth, RLS, tiempo real, consultas lentas), auditorías proactivas o cuando hay un error sin saber por dónde empezar.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)