Claves de Acceso
DYPAI expone un conjunto pequeño de claves y tokens para contextos diferentes. La regla principal es:
- usa
jwtpara flujos de usuario - usa la
API Keydel proyecto solo para llamadas server-to-server - trata
service_rolecomo interno/admin
Trata todas las claves como contraseñas. Nunca expongas la API Key del proyecto ni credenciales service_role en código del navegador, repositorios públicos o variables NEXT_PUBLIC_*.
Las Tres Credenciales
API Key
Usa la API Key del proyecto para endpoints configurados con auth_mode: "api_key".
- Se envía mediante
X-API-KEY - Solo se acepta en endpoints configurados explícitamente con
auth_mode: "api_key" - Está pensada solo para entornos server-side
- Ideal para jobs backend, workers, cron, Route Handlers e integraciones server-to-server
- No debe usarse en navegador ni clientes móviles
Service Role Key
Es una credencial interna de alto privilegio.
- Se envía mediante
Authorization: Bearer <clave> - Otorga acceso interno
service_role - Queda reservada para infraestructura de confianza, operaciones admin, migraciones o tooling privado
- No forma parte del diseño normal de aplicaciones
- Nunca la expongas fuera de un contexto de servidor seguro
MCP Token
Usa el token MCP para conectar IDEs con IA como Cursor o Claude Desktop a tu proyecto.
- Se usa en la configuración MCP
- Permite a tu asistente inspeccionar y operar recursos del proyecto
- Se encuentra en Access → MCP Tokens
Cual Debo Usar
| Credencial | Donde usarla | Header | Caso tipico |
|---|---|---|---|
| JWT de usuario | Browser o app movil | Authorization: Bearer <user-token> | Flujos con usuario autenticado |
| API Key | Solo codigo server-side | X-API-KEY | Endpoints server-to-server |
| Service Role Key | Solo backend interno | Authorization: Bearer <clave> | Operaciones internas/admin |
| MCP Token | Config MCP del IDE | Config MCP | Conexion del IDE con IA |
Uso Con El SDK
App orientada a usuario
Para auth en browser o app, inicializa el SDK solo con la URL del proyecto:
import { createClient } from '@dypai-ai/client-sdk'
const dypai = createClient(process.env.NEXT_PUBLIC_DYPAI_URL!)
Este es el setup normal para:
- login
- signup
- recovery password
- llamadas desde UI a endpoints
jwt
App server-side
Si necesitas llamar endpoints api_key desde backend:
import { createClient } from '@dypai-ai/client-sdk'
const dypaiServer = createClient(
process.env.DYPAI_URL!,
process.env.DYPAI_API_KEY
)
Guarda las claves en variables de entorno server-only y nunca las hardcodees en el código fuente.
# .env
DYPAI_URL=https://tu-proyecto.dypai.app
DYPAI_API_KEY=tu-api-key-del-proyecto
DYPAI_SERVICE_KEY=tu-service-key-interna
Patron Recomendado
Para la mayoria de proyectos:
- Usa
jwtpara endpoints y pantallas orientadas al usuario. - Usa
api_keysolo para automatizacion backend o integraciones server-side. - Deja
service_rolefuera de la arquitectura normal de la app.
Si empiezas con automatizacion backend antes de tener auth de usuarios, puedes trabajar primero con endpoints api_key. Cuando lleguen los flujos de usuario, añade endpoints jwt para esas acciones.
Buenas Practicas De Seguridad
- No expongas la API Key del proyecto en código del navegador
- No pongas
DYPAI_API_KEYen variablesNEXT_PUBLIC_*ni equivalentes - Reserva la Service Role Key para procesos backend internos de confianza
- Rota las claves si sospechas compromiso
- Añade
.enva.gitignore
Siguientes Pasos
- Autenticación — Entiende usuarios, roles y protección de endpoints
- Endpoints — Construye y expone tus propios endpoints
- SDK Auth — Implementa login, signup y recovery