Claves de API y autenticación
Las solicitudes Telemetry API utilizan una clave de equipo API. Trate la clave como una credencial de producción: créela para una carga de trabajo con nombre, asígnele el alcance mínimo requerido, guárdela fuera del control de código fuente y revoquela cuando se retire la carga de trabajo.
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 |
|---|---|
read |
Consultas, descubrimiento de tablas, esquemas e informes de solo lectura |
write |
Ingestión de eventos y operaciones de escritura admitidas |
read-and-write |
Un servidor confiable o una automatización que debe enviar y consultar datos. |
Una aplicación que solo emite eventos normalmente necesita write. Un trabajo de informes normalmente necesita read. Evite darle una clave de equipo a un navegador, una aplicación móvil, un repositorio público o un script creado por el usuario.
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 de SDK acepta la misma clave API. Mantenga la inicialización en el código del lado del servidor y utilice una variable de entorno o una búsqueda de administrador secreto:
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
No utilice un prefijo de tiempo de compilación público como NEXT_PUBLIC_ ni serialice la clave en la configuración del cliente.
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 aparece una clave en una confirmación, registro, captura de pantalla, mensaje o paquete de cliente público, trátela como comprometida. Revocarlo inmediatamente, reemplazarlo y revisar las tablas del equipo afectado y la actividad de consultas.
Continúe con Registro API, Consulta API y orientación sobre datos confidenciales.