Claves de API y autenticación
Las solicitudes a la API de Telemetry aceptan una clave de prueba anónima o una clave del equipo. Mantén las claves privadas y úsalas solo en código de servidor de confianza. La única excepción es una clave de solo ingesta, que solo puede enviar eventos y se puede incluir sin riesgo en un navegador, una app móvil o una CLI.
Empieza con una clave anónima
La página de inicio incluye una clave anon_… en el prompt. Permite enviar eventos, ejecutar SQL y consultar metadatos de tablas sin una cuenta. Las consultas duran 24 horas desde el primer evento. Crea una cuenta en 7 días para conservar los datos. Una prueba sin eventos caduca a los 7 días.
El registro detecta la prueba en el mismo navegador. Si cambiaste de navegador o perdiste el enlace privado, elige ¿Ya tienes una clave API anónima?, pega la clave y pulsa Buscar mis datos. Regístrate o inicia sesión y confirma el vínculo en Conservar mis datos. Los eventos permanecen en su espacio y la clave original sigue funcionando. Una prueba caducada no se puede recuperar.
Gestiona las claves de la cuenta
Crea claves para tareas concretas, dales los permisos mínimos, guárdalas fuera del control de versiones y revócalas cuando dejen de usarse.
Abra Configuración del equipo → Claves API para crear o administrar claves. El valor completo es una credencial, así que cópiela en el administrador de secretos de destino en lugar de en un documento o problema compartido.
Elija el alcance más estrecho
Telemetry admite tres ámbitos:
| Alcance | Úselo para |
|---|---|
ingest |
Solo envío de eventos. Se puede incluir sin riesgo en navegadores, apps móviles y CLI |
read |
Consultas, descubrimiento de tablas, esquemas y listado de paneles y alertas |
read-and-write |
Todo, incluido eliminar datos, cambiar tablas y gestionar paneles y alertas. Para servidores de confianza y agentes de programación |
Una aplicación que solo emite eventos necesita ingest. Un trabajo de informes necesita read. Solo las claves read-and-write pueden eliminar datos, cambiar la retención o las particiones, eliminar tablas o crear y modificar paneles y alertas, así que nunca incluyas una en un navegador, una aplicación móvil, un repositorio público o un script creado por usuarios. Las claves creadas como «Solo escritura» antes de octubre de 2026 ahora son claves ingest.
enviar la clave
Los puntos finales HTTP aceptan la clave como el valor sin procesar de Authorization o como un token al portador:
curl https://api.telemetry.sh/tables \
-H "Authorization: Bearer $TELEMETRY_API_KEY"
La inicialización del SDK acepta la misma clave de API. En el código del servidor, utilice una variable de entorno o un gestor de secretos:
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
Nunca exponga una clave de prueba anónima, read o read-and-write mediante un prefijo de compilación público como NEXT_PUBLIC_ o la configuración del cliente. Un cliente que solo envía eventos puede usar una clave ingest. Créela con el permiso Ingest only en Team Settings → API Keys y confirme su alcance antes de incluirla en una versión pública.
Una clave de solo ingesta no puede consultar los eventos que envía ni administrar el espacio de trabajo. Compruebe los eventos de la aplicación en el panel de Telemetry o use una clave read independiente en un script de servidor de confianza. No incluya esa clave de lectura en el cliente. Registre solo los campos que quiera enviar; una clave de solo escritura no hace segura la recopilación de datos privados.
Claves separadas por carga de trabajo
Utilice claves distintas para la ingesta de producción, la preparación, los informes programados y la configuración del agente de codificación. Las claves específicas de la carga de trabajo reducen la rotación y la respuesta a incidentes: revocar una clave de informes no debería interrumpir la ingesta de eventos.
Nombra la clave según su propietario y propósito. Registre dónde se implementa la clave, su alcance y el propietario de rotación esperado sin registrar el valor de la clave en sí.
Rotar y revocar de forma segura
Primero cree una clave de reemplazo, impleméntela en la carga de trabajo, verifique las solicitudes exitosas y luego revoque la clave anterior. Ejercite las rutas de ingesta y consulta al rotar una clave read-and-write.
Si una clave privada aparece en un commit, registro, captura de pantalla, prompt o paquete público del cliente, considérela comprometida. Revóquela, sustitúyala y revise las tablas y consultas del equipo afectado. Una clave ingest incluida deliberadamente en un cliente público sigue siendo de solo escritura, pero cualquiera que la copie puede enviar eventos. Revóquela y sustitúyala si se está usando de forma indebida.
Continúe con Registro API, Consulta API y orientación sobre datos confidenciales.