¿Qué es el acceso a una API? Claves, OAuth y tokens

¿Qué es el acceso a una API?

El acceso a una API es el mecanismo que decide quién puede llamarla y qué puede hacer cada llamante. El cliente demuestra su identidad con una credencial, como una clave de API o un token de acceso (autenticación), y la API comprueba los permisos de esa identidad para la acción pedida (autorización). Además hace posibles los límites de uso, la facturación y los registros de auditoría por consumidor.

Autenticación frente a autorización

• Autenticación (AuthN): ¿quién llama? Una clave o un token válidos lo responden.
• Autorización (AuthZ): ¿puede hacer esto? Una clave válida puede ser rechazada en DELETE /orders/42 porque solo tiene permiso de lectura.

Hacen falta las dos. Muchos incidentes reales no son contraseñas robadas, sino comprobaciones de autorización que faltan en un endpoint que confiaba en cualquier credencial válida. Para la parte de seguridad, véase seguridad de API.

Formas habituales de controlar el acceso a una API

Claves de API

Una cadena aleatoria larga asignada a cada consumidor y enviada en una cabecera como X-API-Key. Es sencilla de implementar y sirve para llamadas entre servidores, pero quien tenga la clave tiene todo lo que la clave permite, y una clave filtrada funciona hasta que se rota. Más en qué es una clave de API.

Tokens de acceso OAuth 2.0

OAuth 2.0 (RFC 6749, en inglés) permite que un cliente obtenga acceso limitado a una API. El token de acceso es una credencial para recursos protegidos y lleva un alcance (scope) y una duración concretos. En el flujo de código de autorización es un usuario quien concede el acceso; en el flujo de credenciales de cliente, un cliente confidencial, como un servicio backend, obtiene un token con sus propias credenciales.

JWT

Un JSON Web Token es un formato de token firmado, muy usado para los tokens de acceso de OAuth, que contiene claims como el sujeto, los scopes y la caducidad. La API puede verificar la firma sin consultar una base de datos. La otra cara: un JWT sigue siendo válido hasta que caduca, así que revocarlo antes exige infraestructura adicional, y su contenido lo puede leer cualquiera que lo tenga, por lo que nunca debe llevar secretos. Puedes inspeccionar la cabecera y el contenido de un token con el decodificador de JWT gratuito.

Bearer tokens

No es un mecanismo aparte, sino la forma en que se envían la mayoría de los tokens: Authorization: Bearer <token>. Quien porta el token obtiene acceso, así que solo debe viajar por HTTPS. Véase bearer token.

TLS mutuo (mTLS)

Cliente y servidor presentan certificados X.509 en el handshake TLS, y el certificado es la identidad. Es sólido entre servicios, pero costoso de operar e incómodo para navegadores. La RFC 8705 (en inglés) describe cómo lo usan los clientes OAuth y cómo se pueden vincular los tokens de acceso a un certificado de cliente.

Un ejemplo de petición

GET /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...

HTTP/1.1 200 OK        (token válido, scope orders:read)
HTTP/1.1 401 Unauthorized  (token ausente o caducado)
HTTP/1.1 403 Forbidden     (token válido, falta el scope)

401 significa que la API no sabe quién eres; 403, que lo sabe y dice que no. Distinguirlos ahorra mucha depuración.

Buenas prácticas

• Mínimo privilegio. Emite scopes acotados, no credenciales para todo.
• Tokens de corta vida. Tokens de acceso breves con refresh tokens que puedas revocar.
• Rotar y separar. Rota las claves con un calendario y usa credenciales distintas por entorno.
• Cabecera, no URL. Las claves en la query string acaban en logs, historial del navegador y proxies.
• Límites de uso por consumidor. El fallo de un cliente no debería ser la caída de todos.
• Registrar la identidad. Sin ella no sabrás a qué accedió una clave filtrada.
• Documentar bien la autenticación. Muestra peticiones de ejemplo completas y qué significa cada 401 y 403.

Errores comunes

• Autenticar pero no autorizar cada endpoint y cada objeto.
• Tokens de larga vida sin forma de revocarlos.
• Una sola clave para desarrollo y producción.
• Secretos en código de cliente, repositorios o correos de soporte.
• Sin gestión de la caducidad en el cliente, de modo que una caducidad normal parece una caída.

Probar y monitorizar APIs con autenticación

Una API que funciona sin token no demuestra nada, así que las pruebas y comprobaciones deben usar credenciales reales. En la monitorización de API de LoadFocus una comprobación puede enviar cabeceras y bearer tokens de OAuth y encadenar peticiones, por ejemplo iniciar sesión, pasar el token a la siguiente llamada y verificar cada paso. Una prueba de carga que se salta la autenticación mide un camino que los usuarios reales nunca recorren, y la emisión de tokens suele ser el cuello de botella. Dos guías lo tratan a fondo: pruebas de rendimiento de API con OAuth2 y pruebas de carga con OAuth2 (ambas en inglés). Véase también monitorización de API.

Preguntas frecuentes: acceso a una API

¿Qué diferencia hay entre una clave de API y un token de acceso OAuth?

Una clave de API suele ser un secreto estático asociado a una cuenta de consumidor. Un token de acceso OAuth lo emite un servidor de autorización, es de corta vida y lleva scopes. Usa claves para tus propias integraciones entre servidores y OAuth cuando los usuarios dan a una app de terceros acceso a sus datos.

¿Son los JWT más seguros que las claves de API?

Tienen propiedades distintas, no son mejores sin más. Un JWT lleva caducidad y scopes y se puede verificar sin consulta, pero es difícil de revocar antes de que caduque. Una clave se revoca fácilmente, pero nunca caduca sola. La seguridad depende sobre todo de cómo guardes, limites y rotes cada una.

¿Cómo se revoca un JWT filtrado?

O bien mantienes en el servidor una lista de denegación y la consultas en cada petición, con lo que pierdes la ventaja de no guardar estado, o bien haces que los tokens de acceso duren poco para que uno filtrado caduque pronto y revocas en su lugar el refresh token.

¿Qué diferencia hay entre 401 y 403?

401 Unauthorized significa que la petición no tiene autenticación válida. 403 Forbidden significa que el llamante está autenticado pero no tiene permiso para esa acción.

¿Cuándo debo usar mTLS?

Cuando ambos extremos son servicios que controlas y quieres una identidad basada en certificados, o cuando un requisito de cumplimiento lo pide. Evítalo con clientes de navegador, donde gestionar certificados no es práctico.

¿Cómo hago una prueba de carga a una API que requiere autenticación?

Usa una cuenta de prueba o un cliente OAuth dedicados, obtén el token como parte de la prueba y reutilízalo en varias peticiones, y mantén la prueba dentro de los límites de esa cuenta. No uses nunca credenciales de usuarios reales de producción.