API pública, claves y webhooks

Antes de comenzar

Abra su proyecto supastack descargado en Visual Studio Code usando Archivo → Abrir carpeta, luego elija Terminal → Nueva terminal. La raíz del repositorio es la carpeta que contiene package.json, aplicaciones y paquetes. Ejecute el comando a continuación y deje su terminal abierta. Si no se reconoce un comando, finalice la guía de instalación de la herramienta antes de continuar.

Lea primero el tutorial de la plataforma. Un servidor es el proceso de la aplicación que responde a las solicitudes del navegador o del teléfono. La web lee apps/web-tanstack/.env.local, Expo lee apps/mobile/.env.local y los comandos de migración de bases de datos leen el .env de la raíz. La demostración de /dashboard sin base de datos es independiente de las cuentas reales de /auth, que necesitan Postgres migrado. Una entrega solo de teléfono o de escritorio necesita un backend web que se ejecute por separado.

• Instale las herramientas y obtenga el código
• Aprender comandos, archivos y configuración
• Completa el tutorial web de primera ejecución

corepack pnpm --filter @supastack/web-tanstack dev

Configuración y ajustes

packages/api define el contrato versionado: esquemas zod para cada petición y respuesta, el sobre de error y el documento OpenAPI servido en /api/v1/openapi y renderizado en /api/docs. Las claves de API del workspace se crean en Ajustes → Desarrolladores; el texto plano se muestra una vez, después solo persiste la clave hasheada.

Las claves llevan prefijo (sk_<env>_…), scope (lectura por defecto) y se resuelven a un workspace en cada petición. Las suscripciones de webhooks salientes se gestionan desde la misma superficie de Desarrolladores.

GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…

Flujo de implementación

Autentica con la clave Bearer; el servidor resuelve el workspace desde la clave, nunca desde un id suministrado por el cliente. Mantén las formas de respuesta versionadas — cambios aditivos dentro de v1, cambios rupturistas detrás de una nueva versión.

Para webhooks salientes, suscribe una URL de endpoint al catálogo de eventos; las entregas se firman y se registran para que los consumidores puedan verificarlas y reenviarlas. Usa webhook-events.ts para el catálogo y webhook-delivery.ts para los intentos.

Verificación y solución de problemas

Verifica que una clave revocada devuelve 401, que una clave con scope insuficiente es denegada y que el documento OpenAPI se parsea. Para webhooks, prueba la verificación de firma, la reentrega tras fallo y que los payloads de eventos nunca lleven secretos de proveedor.