Entrevista de Backend: ¿Cómo diseñas una autenticación segura con claves de API?

Planteamiento y escenarios aplicables

Una plataforma B2B multiinquilino expone APIs de servidor a servidor. Cada cliente puede crear varias claves para diferentes integraciones. El sistema necesita entornos de producción y prueba separados, permisos con alcance definido, cuotas por clave y por inquilino, expiración opcional, rotación sin tiempo de inactividad y revocación rápida tras un compromiso de seguridad.

Diseña las rutas de emisión, almacenamiento, verificación, autorización, rotación, revocación y auditoría. Explica también en qué casos las claves de API son la credencial equivocada. El cliente es un servidor de confianza capaz de proteger un secreto; las aplicaciones de navegador y móviles quedan fuera de este modelo de credenciales.

El diseño debe preservar cinco invariantes:

1. El secreto completo se muestra una sola vez y nunca se almacena ni se registra en registros (logs) en texto plano.
2. Una clave válida identifica a una entidad principal de máquina (machine principal), pero no autoriza automáticamente todas las acciones.
3. Una clave pertenece a exactamente un inquilino y un entorno.
4. La revocación entra en vigor dentro de un objetivo de propagación definido y comprobable.
5. La rotación puede superponer claves antiguas y nuevas sin ocultar qué credencial realizó una solicitud.

Qué evalúa el entrevistador

La primera señal es si el candidato separa la autenticación de la autorización. Verificar un secreto establece qué entidad principal de clave de API envió la solicitud. El servicio aún debe hacer cumplir los alcances (scopes), la política del endpoint, la propiedad del recurso y el aislamiento del inquilino.

La segunda es el manejo de secretos. Una respuesta sólida genera un secreto opaco de alta entropía con un generador aleatorio criptográficamente seguro, lo muestra una sola vez, almacena únicamente un verificador, lo redacta en todas partes y mantiene cualquier pepper del lado del servidor en un gestor de secretos dedicado.

La tercera es el diseño del ciclo de vida. Las claves necesitan nombres, entornos, estado, expiración, alcances, atribución, rotación y revocación. Tratar una clave como una sola cadena permanente en la base de datos deja a los operadores con un uso compartido inseguro y reemplazos disruptivos.

La cuarta es el razonamiento operativo. Las cachés, los límites de tasa (rate limits), los registros, la respuesta a incidentes y la disponibilidad afectan el límite de seguridad. La "revocación inmediata" no es real si una caché de borde (edge cache) acepta una clave revocada durante diez minutos.

Por último, el candidato debe rechazar las claves de API para clientes no confiables y operaciones suficientemente sensibles. Un secreto portador (bearer secret) estático copiado en el código del frontend puede ser recuperado por usuarios y atacantes. Los flujos de trabajo de alto valor o delegados por el usuario pueden requerir credenciales de carga de trabajo de corta duración, OAuth, mutual TLS, firma de solicitudes o controles de paso adicional (step-up).

Preguntas aclaratorias antes de responder

• ¿Quién posee la credencial? Un servicio backend puede proteger un secreto; un navegador, una aplicación móvil, un binario de escritorio o un repositorio público no pueden garantizar el secreto.
• ¿Qué representa una clave? Define si representa una integración de inquilino, una carga de trabajo interna o un ser humano. Este diseño utiliza una entidad principal de máquina propiedad del inquilino, no una sesión de usuario final.
• ¿Qué tan sensibles son las operaciones? Las analíticas de solo lectura y el movimiento de dinero no ameritan controles idénticos.
• ¿Cuáles son los objetivos de revocación y disponibilidad? Elige un objetivo de propagación medible y decide cómo se comporta la autenticación si el almacén de claves principal no está disponible.
• ¿Cómo se aíslan los entornos? Las claves de prueba y de producción necesitan prefijos distintos, límites de datos, permisos y cuotas independientes.
• ¿Qué tan granulares son los permisos? Establece alcances generales más autorización a nivel de recurso; evita un lenguaje de políticas personalizado sin límites a menos que el producto lo requiera.
• ¿Cuántas claves puede crear un inquilino? Un límite previene la proliferación descontrolada de claves y evita que los clientes eludan las cuotas por clave generando credenciales ilimitadas.
• ¿Qué reglas de auditoría y cumplimiento normativo aplican? La retención, la atribución del creador, los datos de último uso, las aprobaciones y el acceso de emergencia pueden estar regulados.

Estructura de respuesta de 30 segundos

“Emitiría una clave con un ID público buscable y un secreto aleatorio opaco, como ak_live_7F3KQ2.m8…Vw. El valor completo se devuelve una sola vez. La base de datos almacena el ID público, el inquilino, el entorno, los alcances, el estado, la expiración y un verificador con clave (keyed verifier), nunca el secreto en texto plano.

En cada solicitud TLS, la puerta de enlace (gateway) extrae la clave de un encabezado, busca la fila por el ID público, recalcula el verificador, lo compara en tiempo constante y comprueba el estado y la expiración. Luego crea un contexto de entidad principal de máquina. Los alcances del endpoint y la propiedad del inquilino se verifican por separado. Los límites de tasa se aplican tanto a la clave como al inquilino, y los registros de auditoría contienen únicamente el ID público.

Para la rotación, se crea una segunda clave, se despliega, se observa el uso de ambos IDs y luego se revoca la anterior. Una filtración desencadena la revocación inmediata sin período de gracia, revisión de registros y reemplazo. La revocación invalida las cachés dentro del objetivo declarado. Usaría credenciales más fuertes o de corta duración para clientes públicos, delegación de usuarios y acciones de alto valor”.

Análisis detallado paso a paso

Paso 1: Modelar la identidad y los registros de claves

Haz de cada clave una entidad principal de máquina distinta. No compartas un único secreto para todo el inquilino entre todas las integraciones. Un registro práctico es:

ApiKey(
  key_id, tenant_id, environment, name, verifier,
  verifier_version, scopes, status, expires_at,
  created_at, created_by, last_used_at
)

key_id es público y buscable. name ayuda a un operador a distinguir entre “exportación de facturación” y “sincronización de almacén”. status admite al menos los estados activo y revocado; la expiración se evalúa de forma independiente. created_by y un last_used_at aproximado mejoran la atribución. No actualices last_used_at de forma sincrónica en cada solicitud: eso crea un punto caliente de escritura (write hot spot). Agrégalo o toma muestras de forma asíncrona cuando una precisión a nivel de minutos sea suficiente.

Los alcances describen capacidades generales como invoices:read. No reemplazan la autorización de recursos. Después de aceptar la clave, una solicitud para la factura 123 todavía necesita una consulta restringida por el tenant_id autenticado. Nunca aceptes un inquilino suministrado por el llamador como la autoridad.

Paso 2: Generar una vez, revelar una vez, almacenar un verificador

Genera un secreto aleatorio de 32 bytes con un generador aleatorio criptográficamente seguro. Esta es una elección de diseño concreta, no un requisito de protocolo universal. Codifícalo en un alfabeto seguro para el transporte y combínalo con un prefijo reconocible y un ID público:

ak_live_7F3KQ2.m8...opaque-secret...Vw

El prefijo permite que las herramientas de soporte identifiquen el tipo de credencial y el entorno sin exponer el secreto. Devuelve la clave completa únicamente en la respuesta de creación exitosa. La interfaz de usuario debe indicar que no se puede recuperar; perderla significa crear un reemplazo.

Almacena HMAC-SHA-256(server_pepper, complete_secret) como el verificador. El pepper permanece en un gestor de secretos, separado de la base de datos. Un resumen simple de SHA-256 es viable para un token suficientemente aleatorio; el verificador con clave añade defensa en profundidad si solo la base de datos queda expuesta. Versiona el verificador para que el servicio pueda migrar algoritmos o peppers. Una migración de pepper debe admitir una verificación dual acotada o un plan deliberado de reemisión de claves; invalidar silenciosamente todas las claves de los clientes es inaceptable.

La creación es una acción de gestión autenticada. Haz cumplir el rol del inquilino, los límites de cantidad de claves, los alcances permitidos, el entorno, la política de expiración y cualquier aprobación requerida antes de generar el secreto. Almacena el registro y devuelve el secreto a través de una respuesta que nunca se almacene en caché. Redacta los encabezados de autorización y los cuerpos de respuesta en las capas de aplicación, proxy, rastreo (tracing), reporte de errores y herramientas de soporte.

Paso 3: Autenticar una solicitud sin ampliar la autoridad

Exige TLS y acepta la clave en un encabezado de autorización o un encabezado dedicado, nunca en la cadena de consulta (query string) de la URL. Las URLs suelen llegar a historiales, analíticas, registros de proxies y datos de referencia (referrer). Divide y valida el formato, utiliza el ID público para una búsqueda indexada y rechaza la entrada con formato incorrecto antes de realizar un trabajo costoso.

Para una fila candidata, recalcula el verificador y utiliza una comparación en tiempo constante. Luego verifica el entorno, el estado activo y la expiración. Devuelve el mismo error externo genérico para claves desconocidas, malformadas, expiradas y revocadas, de modo que el endpoint no se convierta en un oráculo de enumeración de claves. Internamente, registra un código de motivo seguro sin el secreto.

Una verificación exitosa crea un contexto que contiene key_id, tenant_id, entorno y alcances. La política de la ruta comprueba los alcances requeridos; la capa de datos restringe el acceso a ese inquilino y recurso. Los endpoints administrativos o de alto valor pueden rechazar por completo las entidades principales de claves de API o requerir un control adicional.

Paso 4: Limitar el abuso con cuotas en capas y monitoreo

La limitación de tasa no demuestra la identidad, pero limita el daño de una credencial robada o defectuosa. Aplica un límite de ráfaga y sostenido por clave, además de un límite agregado por inquilino. La capa del inquilino evita que un cliente multiplique la capacidad creando muchas claves. Los endpoints costosos pueden necesitar presupuestos ponderados por costo y límites de concurrencia separados.

Registra el ID público de la clave, el inquilino, la ruta, la decisión, la latencia, los metadatos de red de origen permitidos por la política y el ID de correlación de la solicitud. Nunca registres la clave completa, el verificador ni el encabezado de autorización reutilizable. Alerta sobre cambios geográficos o de red inusuales, picos repentinos de fallos, picos de denegación de alcances, claves inactivas que se vuelven activas y tráfico después de un aviso de rotación. Estas son señales de investigación, no pruebas automáticas de compromiso.

Restringe los endpoints de gestión de claves más estrictamente que los endpoints de datos ordinarios. Merecen una autenticación humana fuerte, protección CSRF para consolas basadas en cookies, autorización explícita, eventos de auditoría, límites de creación y, posiblemente, reautenticación o aprobación.

Paso 5: Conciliar el almacenamiento en caché con la revocación rápida

Una búsqueda de verificación indexada es simple y otorga a la base de datos una decisión autoritativa, pero un volumen de solicitudes muy alto puede justificar una caché. Almacena en caché solo el verificador y metadatos mínimos de autorización bajo el ID público, cifra el transporte y mantén las entradas limitadas. Nunca almacenes en caché el secreto presentado.

La revocación escribe primero el estado autoritativo y publica invalidaciones en las puertas de enlace. Un TTL corto es el respaldo si se pierde una invalidación. El producto debe establecer un objetivo medible —para este escenario, que las claves revocadas dejen de autenticarse en todas las puertas de enlace en un plazo de cinco segundos— y probarlo bajo pérdida de paquetes y reinicio de nodos. Un TTL de diez minutos no puede respaldar esa promesa.

Elige el comportamiento ante fallos según el riesgo. Para escrituras sensibles, si no se puede obtener un estado de clave suficientemente actualizado, el sistema debe fallar cerrando el acceso (fail closed). Para lecturas seleccionadas de bajo riesgo, una entrada de caché previamente válida y brevemente desactualizada puede ser una concesión explícita de disponibilidad, pero viola la revocación inmediata estricta y no debe introducirse encubiertamente como valor predeterminado.

Paso 6: Rotar y revocar como flujos de trabajo diferentes

La rotación rutinaria necesita superposición:

1. Crear una nueva clave sin más privilegios que la anterior.
2. Entregarla a través de la ruta de gestión de secretos del cliente.
3. Desplegar y probar en fase canary la nueva clave.
4. Observar las solicitudes por ID público de clave hasta que la clave antigua no tenga actividad.
5. Revocar la clave antigua y verificar que ningún tráfico dependa todavía de ella.

No modifiques el secreto antiguo in situ; dos IDs separados preservan la atribución y la reversión (rollback) durante la migración. La expiración puede forzar una vida útil máxima, pero la expiración forzada sin telemetría de adopción crea interrupciones evitables.

Una sospecha de filtración sigue un orden diferente: revocar primero sin período de gracia, invalidar cachés, identificar el inquilino afectado, los alcances, las rutas y la ventana de tiempo, revisar las evidencias de auditoría, emitir un reemplazo de mínimo privilegio y remediar la fuente de la filtración. Eliminar la fila de inmediato puede borrar evidencia útil del incidente; conserva los metadatos que no contengan secretos según la política.

Paso 7: Saber cuándo las claves de API son insuficientes

Las claves de API son credenciales al portador: la posesión es suficiente para usarlas. No demuestran que el llamador todavía se ejecute en una carga de trabajo esperada, no proporcionan el consentimiento del usuario final ni evitan la reproducción (replay) por sí mismas. Nunca incrustes una clave secreta en JavaScript para navegadores, un binario móvil, código de ejemplo, una imagen de contenedor o un repositorio.

Para cargas de trabajo en la nube, prefiere la identidad de carga de trabajo de corta duración cuando esté disponible. Para el acceso delegado por el usuario, utiliza un protocolo de autorización con consentimiento acotado y tokens que expiran. Para llamadas de servicio a servicio especialmente sensibles, considera mutual TLS o firma de solicitudes para que un valor de base de datos copiado por sí solo no sea suficiente. La elección correcta sigue el modelo de amenazas; añadir todos los mecanismos a todas las APIs solo genera complejidad operativa.

Paso 8: Probar la seguridad, el ciclo de vida y los modos de fallo

Construye una matriz de pruebas adversarias que cubra:

1. prefijos malformados, IDs desconocidos, secretos incorrectos y manejo del verificador en tiempo constante;
2. claves expiradas, revocadas, de prueba usadas en producción y con alcances insuficientes;
3. acceso a objetos entre inquilinos (cross-tenant) tras una autenticación por lo demás válida;
4. redacción de secretos en salidas de proxy, aplicación, rastreo, errores y auditoría;
5. superposición de rotación, telemetría de uso de claves antiguas, expiración y revocación de emergencia;
6. entradas de caché desactualizadas, invalidaciones perdidas, reinicio de puertas de enlace y caída del almacén de claves;
7. cumplimiento de cuotas por clave y por inquilino, incluyendo muchas claves de un solo inquilino;
8. creación concurrente, revocación durante una solicitud en curso y llamadas de gestión duplicadas.

Escanea también los repositorios y la configuración de despliegue en busca de prefijos de claves reconocibles. Un detector es una ayuda de recuperación, no un permiso para colocar secretos en el control de versiones. Verifica simulacros de incidentes con una clave de prueba: mide el tiempo desde la confirmación de la revocación hasta el rechazo en cada puerta de enlace y confirma que los registros conserven la atribución sin conservar el secreto.

Ejemplo de respuesta sólida

“Trataría cada clave de API como una entidad principal de máquina identificada con nombre, propiedad de un inquilino y un entorno. El valor emitido contiene un ID público de búsqueda y un secreto aleatorio opaco. Lo devuelvo una sola vez sobre TLS, almaceno un verificador con clave más metadatos del ciclo de vida y redacto el valor completo de cada capa de registro y rastreo.

La puerta de enlace busca el ID público, recalcula el verificador, lo compara en tiempo constante y comprueba el entorno, el estado y la expiración. La aceptación genera un contexto con el inquilino y los alcances; cada ruta sigue comprobando su alcance y cada consulta de datos sigue haciendo cumplir la propiedad del inquilino. Los límites por clave aíslan una sola integración, mientras que los límites por inquilino detienen la multiplicación de cuotas.

Si los metadatos de verificación se almacenan en caché, la revocación actualiza la fuente de verdad y envía invalidaciones, con un TTL corto como respaldo. Definiría y probaría un objetivo de revocación de cinco segundos. La rotación rutinaria crea una segunda clave, la despliega en canary, observa ambos IDs públicos y luego revoca la anterior. Una sospecha de filtración omite el período de gracia: se revoca, se investigan los alcances y la ventana de actividad de la clave, se emite un reemplazo más restringido y se corrige la fuente de exposición.

No usaría este secreto estático en navegadores ni en aplicaciones móviles, como identidad de usuario final, ni como único control para acciones de alto valor. Esos casos necesitan credenciales delegadas, de corta duración, vinculadas a la carga de trabajo o más fuertes”.

Errores comunes

• Almacenar la clave en texto plano para poder mostrarla de nuevo. La conveniencia de recuperación convierte una lectura de base de datos en una divulgación de credenciales. Muéstrala una vez y admite el reemplazo.
• Usar únicamente un hash global sin metadatos de ciclo de vida. La verificación por sí sola no puede responder preguntas sobre inquilino, entorno, alcance, expiración, atribución o revocación.
• Poner claves en las cadenas de consulta (query strings). Las URLs se copian y registran rutinariamente. Usa un encabezado sobre TLS.
• Tratar los alcances como autorización de inquilino. invoices:read no demuestra que la factura 123 pertenezca al inquilino autenticado.
• Dar a cada integración una sola clave compartida para todo el inquilino. Una filtración tiene entonces un radio de impacto mayor y la atribución se vuelve ambigua.
• Limitar la tasa únicamente por clave. Un inquilino puede crear o rotar múltiples claves y multiplicar su tráfico permitido.
• Afirmar una revocación inmediata mientras se almacena en caché durante minutos. Declara un objetivo de propagación, invalida activamente y prueba los fallos de caché.
• Rotar sobrescribiendo el secreto. Esto elimina la superposición, la atribución, las pruebas canary y una ruta limpia de reversión.
• Usar un secreto estático en un cliente público. La ofuscación no puede crear un límite de almacenamiento confidencial.
• Registrar la credencial para depurar la autenticación. Registra un ID público y un código de motivo seguro; nunca registres el secreto reutilizable.

Preguntas de seguimiento y respuestas

¿Por qué usar un ID público más un secreto en lugar de aplicar hash a toda la clave y escanear cada fila?

El ID público proporciona una búsqueda indexada, un identificador seguro para soporte y una atribución útil. El secreto sigue siendo la prueba. Escanear cada verificador es lento y fomenta registros peligrosos o índices secundarios. El ID público es intencionalmente no secreto, por lo que conocerlo no debe ayudar a derivar el secreto.

¿Es seguro un hash rápido para un verificador de claves de API?

Puede ser seguro cuando el secreto tiene suficiente aleatoriedad criptográfica, porque a diferencia de las contraseñas humanas no se extrae de un diccionario predecible. Un HMAC con clave añade protección cuando la base de datos queda expuesta sin el pepper separado. Los hashes de contraseñas siguen siendo la herramienta adecuada para contraseñas elegidas por humanos; los modelos de amenazas difieren.

¿Cómo se rota el pepper del lado del servidor?

Almacena una versión del verificador con cada fila. Durante una migración acotada, el verificador puede seleccionar el pepper antiguo o el nuevo, y una clave de versión antigua autenticada con éxito puede reverificarse bajo la nueva versión si el secreto presentado está disponible en memoria. Otra opción es una reemisión programada de claves para los clientes. Nunca elimines el pepper antiguo antes de que todos los verificadores dependientes hayan migrado o expirado.

¿Debería last_used_at ser exacto?

Generalmente no. Actualizar una fila en cada solicitud añade carga de escritura y contención. Envía un evento de uso muestreado o agregado y actualízalo periódicamente. Los eventos de auditoría de seguridad pueden permanecer como solo anexables (append-only) en la capa de solicitudes, mientras que la interfaz de gestión etiqueta last_used_at como aproximado.

¿Cómo se gestiona una condición de carrera entre una revocación y una solicitud en curso?

Define el límite explícitamente. La autenticación puede garantizar que las solicitudes que comiencen después de la propagación sean rechazadas. Una operación sensible puede volver a verificar la autorización antes de hacer commit o vincular el estado de la clave autenticada a una política consciente de transacciones. La revocación no puede borrar retroactivamente una operación que ya se confirmó, por lo que la respuesta a incidentes debe inspeccionar esa ventana.

¿Deberían expirar las claves automáticamente?

La expiración limita la exposición indefinida, pero no sustituye a la rotación ni a la revocación. La plataforma debe notificar a los propietarios, exponer el uso de claves antiguas, permitir una superposición segura y rechazar después de la fecha límite. La vida útil máxima adecuada depende del riesgo y de si hay disponibles mejores credenciales de corta duración.

¿Resolvería el robo de claves el uso de listas de permitidos por IP (IP allowlisting)?

Es una restricción adicional opcional para clientes con direcciones de salida estables. No reemplaza la verificación del secreto y puede generar interrupciones o falsa confianza cuando las redes cambian o se comparten proxies. Trátalo como una señal o capa de política, no como la raíz de la identidad.

¿Qué debería contener la respuesta de creación de clave?

Devuelve la clave completa una sola vez, su ID público o prefijo, nombre, entorno, alcances, expiración y metadatos de creación. Marca la respuesta como no almacenable en caché y nunca devuelvas el verificador ni el pepper. Las APIs de listado posteriores devuelven únicamente el identificador público y los metadatos.