# 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.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/concepts/projects-keys-and-tokens/

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 `development` y en `production` son 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](https://docs.sypnia.com/es/reference/planned).

**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](https://docs.sypnia.com/es/self-hosting/configuration).

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](https://docs.sypnia.com/es/sdks/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](https://docs.sypnia.com/es/mcp/authentication).          |
| 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](https://docs.sypnia.com/es/guides/source-maps-in-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](https://docs.sypnia.com/es/cli).                                                                                       |

## Motor y Cloud: quién crea qué

|                       | Motor de Sypnia (código abierto, en tu propia infraestructura)  | Sypnia Cloud (servicio 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](https://docs.sypnia.com/es/cloud/organizations-and-teams). Las llamadas y los comandos exactos están en la [referencia de la API](https://docs.sypnia.com/es/api/projects-keys-and-tokens) y en la [referencia de la CLI](https://docs.sypnia.com/es/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 `read` y `replay`.
- 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.
