Buenas prácticas de clave

La clave es la contraseña de su integración. Quien tiene la clave hace, por la API, todo lo que ella permite, en nombre del miembro que representa. No hay segundo factor ni confirmación por correo. Cuidar la clave es cuidar la cuenta.

La clave se muestra una sola vez

El servidor guarda solo un hash SHA-256 de la clave. Ni el soporte puede leer una clave ya creada. Se muestra en la pantalla de confirmación de la creación y no vuelve a aparecer.

El cuerpo de la clave son 32 bytes sorteados por el generador criptográfico del sistema. Nadie llega a una clave por tanteo. El riesgo real es que la clave se filtre, y para eso sirve esta página.

Perdió la clave: rótela o cree otra. No hay recuperación.

Dónde guardarla

Guárdela en la bóveda de secretos de su proveedor o en una variable de entorno del servidor que hace las llamadas.

Nunca guarde la clave:

En el código. Ni en un archivo de configuración versionado, ni en una constante “temporal”.
En un repositorio, aunque sea privado. Quien clona se lleva la clave, y el historial de git conserva lo que usted borró después.
En el navegador o en una aplicación móvil. Cualquier persona que abra la página lee la clave. El CORS de la API libera solo las pantallas del propio Faturei Hoje, así que el navegador de otro sitio ni siquiera llega a leer la respuesta.
En una dirección. La API no lee la clave desde un parámetro de consulta. Una dirección con la clave adentro se filtra en el registro del proxy, en el historial del navegador y en el encabezado Referer.
En una planilla, un chat o un ticket de soporte. Nunca le pedimos la clave.

La API acepta la clave en un solo lugar, el encabezado Authorization en formato Bearer. Vea Autenticación.

Búsqueda de secretos

El formato de la clave es fácil de buscar: fh_live_, 43 caracteres de cuerpo y 6 de verificación. Una regla que coincida con ese diseño acierta casi siempre.

Esa regla la configura usted, en la búsqueda de secretos de su proveedor de git o en su propio flujo. Ningún proveedor reconoce este formato por sí solo.

Cuando la inscripción en el programa de búsqueda de secretos de GitHub esté activa, una clave encontrada en un repositorio público de GitHub se revocará automáticamente, los endpoints de webhook registrados con ella se pausarán (motivo emergency_key_rotation, el mismo de la rotación “Detener ahora”) y el dueño y los administradores recibirán un correo con la dirección donde apareció. La inscripción todavía no está activa: hasta entonces, la regla de arriba sigue siendo suya.

Una clave por integración

Cree una clave para cada sistema que integra, con un nombre que diga cuál es. Tres motivos:

Revocar una no tumba las demás. Cuando una clave se filtra, usted cambia solo esa.
El registro de uso queda legible. Con una clave por sistema, lo que aparece en Ver uso es lo que ese sistema hizo, y no la suma de todos.
El permiso queda del tamaño correcto. Cada sistema recibe solo lo que usa.

Lo mismo vale para sus ambientes. No existe clave de prueba ni ambiente de prueba: fh_test_ queda reservado y nunca se emite. Si usted tiene producción y homologación, cada una necesita su propia clave, si no apagar una apaga las dos.

El permiso más pequeño que resuelve

Marque solo lo que la integración usa. El panel trae atajos para empezar: Solo lectura, Formulario del sitio y Acceso total.

Dos límites que ya vienen de fábrica:

La clave nunca hace más que el miembro que representa. El permiso efectivo es la intersección del permiso de la clave con el rol y los permisos del miembro, con el plan de la empresa por encima. Está explicado en Permisos.
Nadie emite una clave por encima de su propio rol. Un ADMIN no crea una clave que represente al OWNER.

Cuando el miembro es suspendido, removido o tiene el acceso desactivado, su clave deja de responder en el acto, con 401. Es lo que hace que “apagar a la persona” apague también sus integraciones.

Plazo de vigencia

En la creación usted elige entre no vence, 30 días, 90 días o 1 año. Después de esa fecha la clave responde 401 como cualquier clave inválida, sin aviso previo.

El plazo reduce la ventana de daño de una clave olvidada. Si elige uno, anote la fecha junto con el recordatorio de cambiarla.

Rotar no renueva el plazo: la clave nueva hereda la fecha de la antigua. Vea Rotación.

Acompañe el uso

En el menú de la clave, en Ver uso, están las llamadas de los últimos 30 días con fecha, método, ruta, estado, duración, IP y request_id. La llamada rechazada también entra, siempre que la API haya reconocido de qué clave se trata. La tarjeta de la clave muestra además la fecha del último uso y cuántas IPs hay en su lista.

Qué vale la pena buscar ahí:

una llamada desde una IP que no es suya;
una secuencia de 401 que usted no esperaba;
uso reciente en una clave que usted creía apagada;
una llamada en una ruta que esa integración no debería usar.

El OWNER y el ADMIN de la empresa reciben un correo cuando una clave se crea, se edita, se rota o se revoca. Un correo que nadie del equipo esperaba es una señal.

Si la clave se filtró

Revoque ahora. El efecto es inmediato, no hay deshacer y no hay período de gracia. Si necesita la integración en el aire, rote eligiendo Detener ahora: eso genera la clave nueva y mata la antigua en la misma acción.
Cambie el secreto en sus sistemas y confirme con una llamada a GET /public/v1/me.
Lea el registro de uso de los últimos 30 días buscando una llamada que no fue suya. Guarde los request_id de lo que parezca extraño.
Saque la clave de donde se filtró. Revocar no borra la copia que quedó en el historial de git, en un registro o en una conversación.
Si hubo uso indebido, escriba a dev@fatureihoje.com con lo que encontró. Vea Reportar una falla.

Próximo paso

IPs permitidas: cuándo la traba por dirección ayuda y cuándo tumba la integración.
Rotación: cambiar el secreto sin tumbar nada.
Autenticación: el formato de la clave y la guía del 401.