Proyectos, entornos, llaves y tokens
A dónde pertenecen tus datos en Sypnia, y qué pueden y qué no pueden hacer exactamente una llave de ingesta, un token de API y el token raíz.
Esta página es para quien configura Sypnia: explica a dónde pertenecen los datos y quién puede llegar a ellos. Los proyectos, los entornos, las llaves de ingesta y los tokens de API funcionan igual en el motor de código abierto y en Sypnia Cloud. Lo que cambia es quién los crea, y de eso trata la última sección.
Proyecto
Un proyecto es una app que Sypnia vigila. Cada evento, sesión, problema, versión y comprobación de disponibilidad pertenece a un solo proyecto, y nada se comparte entre proyectos. Cada fila de la base de datos y cada objeto del almacenamiento lleva su proyecto.
Usa un proyecto por app, aunque la app tenga varias partes. El frontend web de la tienda y su API envían los dos al proyecto shop. Eso es lo que le permite a Sypnia seguir una petición desde el clic hasta la base de datos: una traza solo une partes del mismo proyecto.
Usa proyectos separados para apps separadas, por ejemplo la tienda y su panel de administración.
Entorno
Un entorno dice dónde corre una versión de tu app: production, staging, development, o el nombre que elijas. Tu app lo define cuando inicia el SDK. Si no define nada, el entorno es production.
Los entornos no se crean. Uno existe apenas llega un evento con su nombre. Un proyecto tiene como máximo 20 nombres de entorno: un evento que trae el número veintiuno se descarta, y la respuesta de la ingesta lo cuenta.
Los entornos mantienen los datos separados dentro de un proyecto:
- Las sesiones, los problemas, las trazas y los números de rendimiento siempre se muestran de un entorno a la vez.
- La misma falla en
developmenty enproductionson dos problemas, uno en cada uno. - Las alertas y el resumen diario solo cubren
production. Tus propias pruebas no te despiertan. - En Sypnia Cloud, los límites del plan cuentan juntos todos los entornos de un proyecto.
Llave de ingesta
Una llave de ingesta es la forma en que tu app demuestra a qué proyecto le envía. Empieza por spk_.
| Qué puede hacer | Enviar eventos, grabaciones y capturas de página a su proyecto. |
| Qué no puede hacer | Leer nada. Cambiar nada. Llegar a otro proyecto. |
| Dónde vive | En el código de tu app: el SDK del navegador, el SDK del servidor o un exportador de OpenTelemetry. |
| ¿Es secreta? | No. Es pública por diseño y es seguro publicarla en un navegador. |
| Cuántas | Una o más por proyecto, hasta 20 sin revocar. Dale una propia a cada app o plataforma, así puedes revocar una sin detener las demás. |
Como la llave es pública, cualquiera que lea el código de tu página puede enviar eventos a tu proyecto con ella. Sypnia limita el daño de cuatro formas:
- La llave solo puede escribir.
- La ingesta revisa la forma y el tamaño de todo lo que recibe.
- Hay límites por llave y por proyecto. Una llave acepta 600 peticiones por minuto desde una misma dirección, salvo que le pongas otro número.
- Un proyecto puede listar los orígenes permitidos para enviar datos del navegador, por ejemplo
https://yourapp.com. Mientras la lista esté vacía, se acepta cualquier origen. Las peticiones sin origen, como las que salen de tu servidor, siempre se aceptan.
Si alguien abusa de una llave, revócala y crea otra. Al lanzar, la llave de ingesta es la única credencial para enviar. Una identidad firmada, para apps que necesitan una prueba de quién envía, está planeada.
Para rotar una llave sin perder datos: crea una segunda llave, despliega tu app con ella y después revoca la primera. Una llave revocada se rechaza en menos de un minuto.
Token de API
Un token de API lee los datos de tu proyecto, por la API HTTP, la CLI y el servidor MCP. Empieza por sps_. Es un secreto: trátalo como una contraseña.
Un token pertenece a un proyecto y lleva uno o más alcances.
| Alcance | Qué agrega | Quién suele tenerlo |
|---|---|---|
read | Leer los problemas, la lista de sesiones y la línea de tiempo de cada sesión, las trazas, los números de rendimiento, los resultados de disponibilidad, las versiones y las alertas. Sus únicos cambios son marcas que se pueden deshacer y quedan registradas: resolver o reabrir un problema, confirmar una alerta, cambiar el estado de una sugerencia. | Tu agente de código por MCP. Un script. |
replay | Leer las grabaciones y las capturas de página: lo que una persona vio en su pantalla. | Un agente de código que deba leer grabaciones. Una persona que usa la Consola. |
ci | Registrar versiones y subir source maps, y nada más. No puede leer datos ni cambiar la configuración, así que el secreto que guardas en un sistema de CI le sirve de poco a quien lo encuentre. | Tu CI. |
admin | Cambiar todo lo demás: crear y revocar llaves y tokens, cambiar la configuración del proyecto, administrar las comprobaciones de disponibilidad, las reglas de alerta y los webhooks, ignorar un problema, pedir un análisis nuevo o un pull request, borrar datos. También puede hacer lo que hace ci. | Tú. |
Fuera de eso, los alcances no se incluyen entre sí. Un token que deba leer y administrar necesita read y admin; un token de CI que solo sube source maps necesita solo ci.
Reglas que valen para todos los tokens:
- Se muestra una sola vez, al crearlo. Sypnia guarda solo un hash y no puede volver a mostrarlo.
- No vence, salvo que le pongas una fecha de vencimiento al crearlo. Funciona hasta esa fecha o hasta que lo revoques, y un token revocado se rechaza en menos de un minuto.
- Un proyecto tiene como máximo 50 tokens sin revocar.
- No puede enviar eventos. Enviar es trabajo de la llave de ingesta.
- Sin el alcance
replay, un token puede ver que una sesión tiene grabación, pero no puede leerla.
Dale a cada herramienta su propio token con los alcances mínimos que necesita. Si se filtra el token de tu agente de código, revocas ese y nada más se detiene.
Token raíz Motor
Un motor en alojamiento propio tiene una credencial más: el token raíz. Lo eliges tú, una cadena de 32 caracteres o más, y lo defines en el entorno cuando instalas el motor (SYPNIA_ROOT_TOKEN). Mira la referencia de configuración.
El token raíz puede hacer todo en todos los proyectos, incluidas las dos cosas que ningún token de API puede hacer: crear un proyecto y borrarlo. Úsalo para crear tus proyectos y sus primeros tokens, y después guárdalo. No se lo des a una app, a un agente de código ni a un job de CI. Para cambiarlo, cambia el ajuste y reinicia el motor.
Sypnia Cloud no tiene token raíz. Allí las personas inician sesión.
Qué credencial va en cada lugar
| Estás configurando | Usa | Por qué |
|---|---|---|
| El SDK del navegador | Una llave de ingesta | Solo necesita enviar. |
| El SDK de Node o de Next.js | Una llave de ingesta | Lo mismo. |
| Un exportador de OpenTelemetry | Una llave de ingesta | Lo mismo. Mira OpenTelemetry. |
| Tu agente de código, por MCP | Un token de API con read, más replay si debe leer grabaciones | Lee, y puede marcar un problema como resuelto cuando lo arregla. Mira Autenticación de MCP. |
| La subida de source maps en CI | Un token de API con ci | Registra la versión y sube sus source maps, y no puede hacer nada más. Mira Source maps en CI. |
| La CLI en tu propia máquina | Un token de API, o el token raíz en un motor en alojamiento propio | Mira la referencia de la CLI. |
Motor y Cloud: quién crea qué
| Motor de SypniaCódigo abierto, en tu propia infraestructura | Sypnia CloudServicio pago, con un plan gratis | |
|---|---|---|
| Quién entra | Quien tenga un token. No hay usuarios ni organizaciones. | Personas con una cuenta, que pertenecen a una organización y tienen un rol. |
| Crear un proyecto | Con el token raíz, por la CLI o la API. Todos los que quieras. | En la app, un dueño o un administrador. El plan define cuántos. |
| Crear llaves y tokens | Con el token raíz, o con un token de API con el alcance admin. | En la app, un dueño o un administrador. También por la API con un token admin. |
| Leer los datos | La Consola, la API, la CLI y MCP, cada una con un token de API. | La app, después de iniciar sesión. La API y MCP con un token de API. |
Los roles de Sypnia Cloud se describen en Organizaciones y equipos. Las llamadas y los comandos exactos están en la referencia de la API y en la referencia de la CLI.
Ejemplo: la tienda
La tienda tiene un proyecto, shop, con dos entornos, production y development.
- El frontend web y el servidor de la API usan cada uno una llave de ingesta. Podrían compartir una; con dos, una se puede rotar sin tocar la otra.
- Cursor está conectado por MCP con un token de API que tiene
readyreplay. - El job de CI que sube los source maps después de cada despliegue tiene su propio token con
ci.
Cuando el botón Pagar se rompe en producción, se vuelve un problema en shop / production. El mismo error visto durante las pruebas en development es un problema aparte allí, y no envía ninguna alerta.