# Autenticación y Mind Keys
SUMMARY: Cómo funciona la autenticación de Synapse: Mind Keys para agentes, JWTs para humanos, ?key= para herramientas que solo usan URL.

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

Autenticación y Mind Keys
Synapse usa dos métodos de autenticación, cada uno optimizado para un caso de
uso diferente. Comprender la diferencia es esencial para construir integraciones
fiables.
Dos métodos de autenticación
| Método | Caso de uso | Límite de frecuencia | Expiración |
|--------|----------|------------|--------|
| Mind Key | Agentes LLM, herramientas automatizadas | Ninguno (cabecera) / 60 min (query) | Nunca |
| JWT | Interfaz humana, operaciones de cuenta | Ninguno | 7 días |
Mind Key (para agentes)
Un Mind Key es un token de API con ámbito de tenant. Autentica los datos de un
solo mind (memorias, tareas, chat, scripts, etc.). Úselo para:
- Agentes LLM que llaman a la API
- Scripts de automatización en segundo plano
- Configuración del servidor MCP
- Cualquier integración de larga duración
Autenticación por cabecera (recomendada)
[CODE BLOCK]
Parámetro de consulta (para herramientas que solo usan URL)
[CODE BLOCK]
> [!WARNING]
> El parámetro de consulta  está limitado a 60 peticiones por minuto.
> La cabecera Bearer no tiene límite de frecuencia. Use la cabecera siempre que
> su cliente admita cabeceras personalizadas.
Crear un Mind Key
[CODE BLOCK]
La respuesta incluye  — guárdelo de inmediato, solo se muestra una
vez.
Listar sus minds
[CODE BLOCK]
Eliminar un mind (¡irreversible!)
[CODE BLOCK]
JWT (para humanos)
Los JWT autentican la cuenta de usuario, no un mind específico. Úselos para:
- Registro y login de cuenta
- Crear / listar / eliminar minds
- Compartir minds con otros usuarios
- Gestión de suscripciones Web Push
Registro
[CODE BLOCK]
Devuelve: 
Login
[CODE BLOCK]
Devuelve: 
Expiración del JWT
Los JWT expiran después de 7 días. Cuando un JWT expira, simplemente llame
a  de nuevo para obtener uno nuevo. El Mind Key nunca expira, de modo
que las integraciones de agente existentes siguen funcionando.
Mejores prácticas de seguridad
> [!CRITICAL]
> - Nunca confíe Mind Keys a git. Use variables de entorno.
> - Nunca registre Mind Keys en logs. Enmascárelos ().
> - Rote las claves si sospecha de una fuga (elimine el mind, cree uno nuevo).
> - Use un mind por proyecto para limitar el radio de impacto si se filtra una clave.
Patrón con variables de entorno
[CODE BLOCK]
[CODE BLOCK]
Configuración del servidor MCP
[CODE BLOCK]
Patrón multi-mind
Cada usuario puede tener múltiples minds. Patrones comunes:
| Nombre del mind | Propósito |
|-----------|---------|
|  | Memorias de trabajo |
|  | Preferencias personales, familia |
|  | Contexto de un proyecto específico |
|  | Progreso de aprendizaje |
|  | Fallback de propósito general |
Use diferentes Mind Keys para diferentes sesiones LLM a fin de mantener los
contextos aislados.
Límites de frecuencia
| Método de auth | Límite | Ámbito |
|-------------|-------|-------|
| Mind Key (cabecera) | Ninguno | Por mind |
| Mind Key (?key=) | 60/min | Por IP |
| JWT (cabecera) | Ninguno | Por usuario |
| Endpoints públicos | Ninguno | Global |
Las cabeceras de límite de frecuencia (,
, ) se incluyen en las respuestas cuando
aplica.
Próximos pasos
- Mind Key vs JWT — cuándo usar cada uno
- API de Memory — qué puede hacer con un Mind Key
- API de User — gestión de cuenta con JWTs