Seguridad de tokens de API: buenas prácticas

Un token de API es la llave de un servicio que cuesta dinero. Si consume créditos de consultas RUC o DNI, cada petición que haga un tercero con tu token la pagas tú. Y a diferencia de una contraseña, un token suele viajar por muchos lugares: código, archivos de configuración, pipelines, servidores, laptops de desarrolladores.

Las filtraciones casi nunca vienen de un ataque sofisticado. Vienen de un git push con el .env incluido, de un token pegado en el JavaScript del navegador "mientras probamos" o de un repositorio que pasó de privado a público. Son errores de descuido, y por eso se previenen con hábitos, no con herramientas caras.

Esta guía reúne las prácticas que importan: dónde no debe estar nunca un token, dónde sí, cómo rotarlo, qué hacer si se filtra y cómo vigilar el consumo.

---

Un token es una contraseña con otro nombre

Cuando llamas a una API con Authorization: Bearer TU_TOKEN, el servidor no pregunta quién eres: asume que quien porta el token es su dueño. Eso es lo que significa "Bearer" (portador). No hay segundo factor ni verificación de origen. Quien tenga la cadena de texto tiene acceso completo a tu cuenta, hasta donde ese token lo permita.

Trátalo como la contraseña de tu banca por internet. No lo escribas en un chat, no lo pegues en una captura ni en un ticket de soporte, no lo envíes por correo. Si necesitas compartirlo con un colega, usa el gestor de contraseñas del equipo.

Y asume que algún día se va a filtrar. Las prácticas que siguen reducen la probabilidad, pero el buen diseño es el que convierte una filtración en un problema de diez minutos (revocar, generar otro, desplegar) y no en una catástrofe. Si recién empiezas con APIs, integrar una API REST con token en 5 minutos muestra el token en acción.

Nunca en el frontend

Todo lo que llega al navegador es público. No importa que lo pongas en una variable con nombre raro, que lo ofusques o que lo cargues desde otro archivo: cualquier persona puede abrir las herramientas de desarrollo, ir a la pestaña de red y leer la cabecera Authorization de cada petición. Lo mismo aplica a una app móvil: el binario se puede descomprimir y las cadenas de texto se extraen en minutos.

Esto incluye casos que a veces no se ven como "frontend": un archivo config.js servido por tu web, una variable NEXT_PUBLIC_ o VITE_ en un proyecto moderno (ese prefijo significa justamente que se incluye en el bundle público), o una hoja de cálculo compartida con el token en una celda.

La solución es siempre la misma: el navegador habla con tu backend, y tu backend, que sí guarda el token, habla con la API. Tu endpoint intermedio valida la entrada, consulta, y devuelve al frontend solo los campos que necesita. En consultar RUC con Node.js hay un ejemplo completo de ese endpoint en Express, y el patrón de autocompletar nombres con el DNI sigue la misma regla desde el formulario.

Ese endpoint tiene que estar protegido: si cualquiera puede llamarlo sin iniciar sesión, tu token sigue siendo público con un paso más. Ponle la autenticación de tu aplicación y un límite de peticiones por usuario.

Nunca en el repositorio

Un token en Git es un token filtrado, aunque el repositorio sea privado. Los repositorios cambian de visibilidad, se clonan en laptops que se pierden, se comparten con contratistas, y el historial de commits recuerda todo: borrar el token en el siguiente commit no lo quita del historial.

Tres hábitos lo evitan:

1. Agrega .env y cualquier archivo de credenciales a .gitignore antes del primer commit, no después.
2. Versiona un .env.example con las claves pero sin valores, para que el equipo sepa qué variables necesita.
3. Activa el escaneo de secretos de tu proveedor de Git y, si puedes, un hook de pre-commit que busque patrones de tokens antes de permitir el commit.

# .gitignore
.env
.env.*
!.env.example

# .env.example (este sí se versiona)
ENDPOINT_PE_TOKEN=
DATABASE_URL=

Si un token ya está en el historial, no confíes en reescribir commits como única medida: es laborioso, rompe los clones del equipo y no garantiza que nadie lo haya copiado antes. Lo primero es revocar el token y generar uno nuevo; limpiar el historial es secundario.

Variables de entorno y gestores de secretos

El lugar correcto para un token es fuera del código: en el entorno del proceso que lo necesita. En desarrollo, un archivo .env local (ignorado por Git) que tu framework o un paquete como dotenv carga al arrancar. En producción, variables definidas en el servidor, en el panel de tu plataforma de hosting, en el orquestador de contenedores o en un gestor de secretos.

El código solo lee la variable y falla rápido si no existe:

const token = process.env.ENDPOINT_PE_TOKEN;

if (!token) {
  throw new Error('Falta la variable de entorno ENDPOINT_PE_TOKEN');
}

Ese throw al arrancar vale oro. Es mucho mejor que la aplicación se niegue a iniciar que descubrir en producción que todas las consultas devuelven 401 porque alguien olvidó configurar la variable en el nuevo servidor.

Un gestor de secretos (de tu proveedor de nube o autoalojado) da un paso más: los tokens se guardan cifrados, se auditan los accesos y se rotan sin tocar el código. Para un solo servidor puede ser más de lo necesario; para varios entornos y servicios, ordena mucho.

Dos reglas más. Primera: distintos entornos, distintos tokens; así un token filtrado desde la laptop de alguien no compromete producción. Segunda: nunca imprimas el token en logs. Es fácil hacerlo sin querer al registrar "la petición completa" o al volcar la configuración durante un error.

Un token por aplicación y permisos mínimos

Si tres sistemas (tu ERP, la tienda online y un script de limpieza de datos) usan el mismo token, el día que uno se filtra tienes que cambiarlo en los tres a la vez, y nunca vas a saber cuál de ellos lo filtró. Si cada uno tiene el suyo, revocas uno solo y el resto sigue funcionando.

Siempre que tu proveedor lo permita, crea un token por aplicación o por entorno, y ponle un nombre descriptivo (erp-produccion, tienda-staging, migracion-2026). Si el servicio ofrece limitar cada token a ciertas APIs, dominios o direcciones IP, aprovéchalo: un token que solo puede consultar RUC no sirve para nada más si cae en malas manos. Es el principio de mínimos permisos aplicado a credenciales.

Lleva un inventario, aunque sea una tabla simple: qué token existe, para qué sistema, quién lo creó, cuándo, y dónde está configurado. Sin eso, al rotar o revocar vas a adivinar, y adivinar con credenciales de producción nunca sale bien.

Rotación, filtraciones y monitoreo de consumo

Rotación. Cambiar los tokens de forma periódica limita cuánto tiempo sirve uno que se filtró sin que lo notaras. No hay un plazo mágico; lo importante es que el proceso esté ensayado. Son tres pasos: generar el nuevo token, desplegarlo en todos los lugares donde se usa y recién entonces revocar el antiguo. Si revocas primero, tienes una ventana de caída.

Si se filtra. El orden importa: primero revoca, luego investiga. Cada minuto que el token siga activo es consumo que pagas tú. Después, genera uno nuevo y despliégalo, revisa el consumo de los últimos días para ver si hubo uso ajeno, y busca el token filtrado en el historial de Git, en logs, en el CI y en herramientas de chat para entender por dónde salió. Cierra ese camino antes de volver a la rutina.

Monitoreo. La mejor alarma es tu propio gráfico de consumo. Si tu sistema hace unas 300 consultas al día y un lunes aparecen 5 000, algo pasó: o un bucle sin control en tu código o alguien más está usando tu token. En endpoint.pe, los planes de pago incluyen un panel con métricas de uso; revísalo con la misma frecuencia con que revisas tus servidores. Si tu proveedor permite alertas por umbral, configúralas.

Complementa el panel con tus propios registros: cuántas consultas hace cada aplicación por día y cuántas terminan en 401, 402 o 429. Un salto en los 401 suele señalar un token revocado que alguien olvidó actualizar; un salto en el total, consumo inesperado. Una caché bien hecha además reduce el ruido de fondo y hace más visible cualquier anomalía.

Al evaluar un proveedor, la seguridad es un criterio eliminatorio: HTTPS, token que se pueda regenerar y tratamiento de datos conforme a la ley. La lista completa de criterios está en cómo elegir una API de consulta RUC y DNI en Perú.

En resumen

• Un token Bearer es una contraseña: quien lo tiene, lo usa. Guárdalo en un gestor de contraseñas y nunca en chats ni capturas.
• Nunca en el navegador ni en apps móviles; el frontend habla con tu backend y el backend con la API.
• Nunca en Git: .env ignorado, .env.example versionado y escaneo de secretos activado.
• Variables de entorno distintas por entorno, falla al arrancar si falta una y nunca la imprimas en logs.
• Un token por aplicación, con nombre, inventario y permisos acotados cuando el servicio lo permita.
• Rota sin ventana de caída (crear, desplegar, revocar) y, si se filtra, revoca primero y luego investiga.

Preguntas frecuentes

¿Es suficiente con que el repositorio sea privado?

No. Los repositorios privados se clonan en equipos que se pierden, se comparten con terceros y a veces pasan a públicos por error. Además, el historial conserva todo. Un token en Git se considera filtrado desde el momento del commit.

¿Qué hago si necesito consultar la API desde una app móvil?

Lo mismo que en la web: la app llama a tu backend, y el backend, con el token, llama a la API. Un binario móvil se descomprime en minutos y cualquier cadena de texto dentro se puede extraer, así que el token nunca debe ir dentro de la app.

¿Cada cuánto debería rotar un token?

No hay una cifra universal. Lo que importa es que rotar sea un proceso ensayado que no cause caídas, y que lo hagas de inmediato ante cualquier sospecha de filtración o cuando alguien con acceso deja el equipo. Si tu empresa tiene una política de rotación de credenciales, aplícala también a los tokens.

¿Cómo sé si alguien está usando mi token sin permiso?

Por el consumo. Compara el uso diario que registra el panel de tu proveedor con el que registra tu propia aplicación: si el proveedor cuenta más consultas de las que tú hiciste, alguien más está usando el token. Revócalo primero, investiga después.