Una clave de API es una credencial que una aplicación presenta al llamar a una API. OAuth 2.0 es un marco de autorización que permite obtener tokens para acceder a determinados recursos. La elección afecta a quién puede conectar una integración, qué permisos recibe y cómo se retira el acceso. Ambos enfoques necesitan controles sobre las credenciales y los permisos; las posibilidades concretas dependen de cómo los implemente el proveedor.
Para un Product Manager, el punto de partida es la integración que se quiere construir. Un cliente que exporta pedidos a su propio sistema de informes tiene necesidades distintas de una aplicación que se conecta a las cuentas de cientos de empresas. El modelo de acceso condicionará la configuración inicial, el soporte y las consecuencias de una credencial comprometida.
Qué permite una clave de API depende del servicio
Una clave de API privada suele ser una cadena de caracteres que genera el proveedor y guarda la aplicación que va a consultar su API. Cuando llega una petición, el servicio comprueba la clave y aplica las reglas de acceso que tenga asociadas. Según el proveedor, puede identificar un proyecto, una aplicación o una cuenta. No necesariamente identifica a la persona que utiliza esa aplicación.
Las claves pueden tener restricciones útiles. Un proveedor puede permitir la lectura de pedidos e impedir los reembolsos, limitar las peticiones a determinadas direcciones de red o permitir una clave independiente para cada integración. Conviene comprobar estas capacidades en la documentación. Stripe, por ejemplo, ofrece claves restringidas con permisos por recurso. La clave de otro servicio puede conceder un acceso mucho más amplio.
Esta comparación se centra en las claves privadas de las integraciones entre servidores. Algunos servicios también ofrecen claves publicables, pensadas para utilizarse en el navegador o en una aplicación móvil; cumplen otra función y no sustituyen a una credencial privada. Si una clave secreta se incluye en una aplicación descargable o en un repositorio público, alguien puede extraerla y utilizarla fuera de la integración prevista.
Cómo cambia la conexión con OAuth
En una conexión OAuth con acceso delegado, una aplicación solicita permiso para acceder a recursos de otro servicio. El usuario inicia sesión en ese servicio y autoriza el acceso solicitado, de acuerdo con las reglas del proveedor. La aplicación recibe un token de acceso que le permite consultar la API sin recoger la contraseña del usuario. Una integración con un calendario, por ejemplo, podría solicitar permiso para leer eventos sin poder modificarlos.
Estos permisos suelen expresarse mediante scopes, o ámbitos de acceso. Su precisión depende de la API: un scope puede cubrir una operación concreta o un conjunto amplio de datos. El token de acceso tiene una duración limitada y algunos flujos también entregan un token de renovación, llamado refresh token, que permite obtener nuevos tokens de acceso. La renovación puede ocurrir en segundo plano, aunque la retirada de permisos o la caducidad del refresh token pueden exigir que el usuario vuelva a conectar la cuenta. Google documenta estos comportamientos para sus APIs.
OAuth también permite la comunicación entre sistemas sin una pantalla de aprobación de un usuario. En el flujo client credentials, una aplicación capaz de proteger sus credenciales obtiene un token para actuar en su propio nombre. Por eso Ingeniería puede proponer OAuth para un proceso B2B que funciona en segundo plano. Lo que hay que aclarar es con qué autoridad actúa la integración, sin deducirlo de la presencia de un botón «Conectar».
OAuth se ocupa de la autorización. Cuando el producto también necesita identificar a una persona para iniciar sesión, es habitual utilizar OpenID Connect, una capa de identidad construida sobre OAuth 2.0. Esta distinción ayuda a definir si la conexión concede acceso a datos, permite entrar en el producto o cumple ambas funciones.
Claves de API frente a OAuth: permisos y ciclo de vida
| Decisión | Clave de API | OAuth 2.0 |
|---|---|---|
| ¿A quién representa? | A una aplicación, un proyecto o una cuenta, según el proveedor. | A una aplicación que actúa en su propio nombre o con acceso delegado. |
| ¿Cómo se limitan los permisos? | Mediante restricciones o roles asociados a la clave, si el servicio los ofrece. | Mediante los scopes y las políticas de autorización que admite el servicio. |
| ¿Cómo comienza el acceso? | Un administrador suele generar y configurar la credencial. | La aplicación obtiene tokens mediante el flujo correspondiente; el acceso delegado puede requerir aprobación de un usuario o administrador. |
| ¿Qué caduca? | La clave puede seguir activa hasta su revocación o caducar según las reglas del proveedor. | Los tokens de acceso caducan; la renovación y la duración del refresh token dependen del flujo y del proveedor. |
| ¿Cómo se retira el acceso? | Se desactiva o elimina la clave correspondiente y se comprueba cuándo deja de aceptarse. | Se revoca la autorización o los tokens correspondientes y se comprueba cuándo dejan de funcionar los tokens ya emitidos. |
| ¿Qué hay que mantener? | Almacenamiento seguro, rotación, restricciones y seguimiento del uso. | Almacenamiento y renovación de tokens, flujos de autorización, revocación y las credenciales propias que utilice la aplicación. |
La comparación debe hacerse con las capacidades del proveedor concreto. Una clave con permisos limitados y un procedimiento fiable de rotación puede servir para un proceso controlado. Una integración OAuth con permisos excesivos o refresh tokens mal protegidos también puede exponer datos sensibles. Los tokens de acceso de corta duración limitan una parte de esa exposición; las credenciales que permiten obtener nuevos tokens siguen necesitando protección.
Dos integraciones B2B con necesidades distintas
En un caso hipotético, un cliente de Mercato, una plataforma de comercio electrónico, quiere copiar sus pedidos cada noche a una herramienta interna de informes. Si la API ofrece una clave de solo lectura limitada a la cuenta de ese cliente, una clave privada puede cubrir la necesidad. Utilizar credenciales distintas para los informes y para la preparación de pedidos permitiría desactivar una conexión sin interrumpir la otra. Una única clave compartida y sin restricciones dificultaría esa separación.
El trabajo de producto incluye decidir quién puede generar la clave, cómo se registra para qué se utiliza y cómo la sustituye el cliente. Rotarla consiste en emitir una credencial nueva y retirar la anterior. Si ese cambio exige una ventana de mantenimiento o la intervención de soporte, habrá que contemplarlo en el plan de la integración. Cuando el proveedor exige OAuth con client credentials, ese mismo proceso de informes tendrá que incorporar la obtención y renovación de tokens.
Una segunda funcionalidad hipotética permite a los comercios conectar una aplicación externa de previsión de ventas. Cada comercio necesita autorizar el acceso a su historial de pedidos, entender los permisos solicitados y retirar la conexión de forma independiente. Un flujo OAuth con acceso delegado encaja bien cuando la API lo admite: el comercio autoriza a la aplicación a través del proveedor, sin copiar una clave privada en el formulario de un tercero.
La conexión puede fallar después de configurarse. Un administrador puede retirar el acceso, la cuenta puede perder un permiso necesario o una credencial puede caducar. El producto de previsión necesita mostrar el estado de la conexión y ofrecer una forma de recuperarla. Reintentar continuamente un error de autorización sin avisar dejaría a los comercios tomando decisiones con previsiones desactualizadas.
Qué debe ocurrir al desconectar una integración
«Desconectar» puede significar detener futuras sincronizaciones, revocar la autorización en el proveedor, eliminar las credenciales guardadas o borrar la información importada. Son operaciones distintas. Retirar una conexión no elimina automáticamente los datos que ya se han copiado, por lo que su conservación y borrado necesitan requisitos propios.
El acceso también puede tardar en desaparecer. Los proveedores OAuth difieren en cómo invalidan los tokens emitidos: revocar un refresh token puede impedir su renovación mientras un token de acceso existente sigue funcionando hasta que caduca. La revocación de claves también depende de cómo la aplique el servicio. El equipo debe conocer ese comportamiento antes de prometer una desconexión inmediata.
Preguntas que conviene resolver antes del lanzamiento
La revisión puede empezar por las operaciones que necesita la integración y la cuenta en cuyo nombre actúa. Eso permite examinar los permisos disponibles y acordar qué ocurrirá al sustituir una credencial o perder el acceso. Estas preguntas pueden convertirse en criterios de aceptación:
- ¿La integración puede leer únicamente los datos necesarios? ¿Puede modificar o borrar información sin necesitarlo?
- ¿Cada cliente e integración pueden tener un acceso independiente y un registro claro de quién lo aprobó?
- ¿Se pueden renovar o rotar las credenciales sin interrumpir los procesos programados?
- Tras la desconexión, ¿durante cuánto tiempo podrían seguir aceptándose peticiones y qué ocurre con los datos importados?
- ¿Quién recibe el aviso cuando falla la autorización y cómo recupera el cliente la conexión?
La guía de APIs para Product Managers explica las peticiones, las respuestas y las dependencias de una integración. Para distinguir entre la identidad y las acciones permitidas, puede consultarse autenticación frente a autorización. Los libros APIs para Product Managers y Seguridad para Product Managers desarrollan estas decisiones de integración y acceso con más detalle.
Referencias técnicas
- Stripe: claves de API y permisos restringidos.
- Google: OAuth 2.0, scopes y renovación de tokens.
- IETF RFC 6749, apartado 4.4: client credentials.
- IETF RFC 7009: revocación de tokens y RFC 9700: prácticas actuales de seguridad para OAuth 2.0.