Autenticación de APIs con API Keys y OAuth 2.0

Autenticación de APIs con API Keys y OAuth 2.0

Resumen

Esta guía explica cómo identificar una aplicación en el Portal, obtener sus credenciales y autenticar solicitudes a las APIs mediante API Keys u OAuth 2.0.

Los ejemplos utilizan valores ficticios. Reemplácelos por los datos de su aplicación y por la URL que figure en la documentación del método.

Antes de comenzar

  • Debe contar con un usuario registrado e iniciar sesión en el Portal para desarrolladores.
  • Debe tener una aplicación creada y con acceso al método que desea consumir.

Dónde encontrar las credenciales

Abra el menú de usuario, ingrese en Mi cuenta y seleccione Mis aplicaciones. Cada aplicación muestra las Llaves de acceso y, cuando corresponde, las credenciales OAuth 2.0. Use el ícono de visualización únicamente en un entorno privado.

Autenticación con API Keys

Las aplicaciones pueden mostrar una Auth Key y una Public Auth Key. La documentación del método indica la llave y la forma de envío esperadas. No intercambie ambas credenciales ni agregue el prefijo Bearer salvo que el método lo solicite expresamente.

Enviar la API Key como parámetro

Cuando el método indica envío por parámetro, agregue auth_key a la URL:
GET https://api.example.com/accounts/v1/accounts.json?auth_key=YOUR_AUTH_KEY

Enviar la API Key en una cabecera

Cuando el método indica envío por cabecera, utilice Authorization con la llave como valor:
curl --request GET \
--header 'Authorization: YOUR_AUTH_KEY' \
'https://api.example.com/accounts/v1/accounts.json'

Autenticación con OAuth 2.0

El flujo mostrado en el portal es Client Credentials. Primero se solicita un access token con el Client Id y el Client Secret; después se envía ese token en cada llamada a la API.

Obtener un token desde el portal

En la documentación del método, la sección Autenticación indica que el token viaja en la cabecera Authorization con el prefijo Bearer, y Permisos disponibles lista los scopes que el método exige. El botón ¿Cómo obtener un token de acceso? muestra la solicitud al endpoint /oauth/token/ y un ejemplo cURL; al elegir una de sus aplicaciones, el ejemplo se completa con su client_id y su client_secret. El portal no muestra el token: lo obtiene su aplicación con esa solicitud, y la vigencia es el valor expires_in de la respuesta.

Solicitar un token con cURL

Realice una solicitud POST al endpoint /oauth/token/ con Content-Type: application/x-www-form-urlencoded:
curl --location --request POST 'https://YOUR_DOMAIN/oauth/token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=ventas'
El scope read es el utilizado en el ejemplo. Solicite solo los scopes que aparecen como requeridos en la documentación del método.

Ejemplo de respuesta:

{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "YOUR_ACCESS_TOKEN",
"scope": "ventas"
}

Consumir la API con el access token

Envíe el token en la cabecera Authorization con el prefijo Bearer:
curl --request GET \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
'https://api.example.com/accounts/v1/accounts.json/'


Una respuesta HTTP 200 confirma que la solicitud fue aceptada. El contenido y código HTTP de la respuesta depende del método consultado.



Proteger un método con OAuth 2.0 desde el Workspace

Esta parte la hace el administrador de la cuenta. Los tokens los emite el proveedor configurado en Configuraciones › Integraciones › OAuth2.0 (Keycloak, Auth0 u Okta); Vortex registra allí los métodos protegidos, sus permisos y las aplicaciones.

Pestaña OAuth2.0 de Integraciones con el proveedor Keycloak y sus campos

Habilitar OAuth 2.0 en el método

En el editor del método, en el bloque Seguridad, el método tiene que ser Privado; recién entonces aparece el botón Habilitar OAuth 2.0. El modal Configuración OAuth2.0 pide:

  • Permisos: los scopes del método. Escriba cada nombre y presione Enter. El token tiene que traer todos los permisos del método para que la llamada pase.
  • Vigencia del Token de acceso, formato 00d 00h 00m 00s, máximo 30 días. Con Keycloak rige la vigencia de la integración de la cuenta.
  • Algoritmo de encriptación: RS256 o HS256.
  • Las casillas Permitir a las aplicaciones refrescar sus tokens y Permitir a las aplicaciones pasar por alto el consentimiento del usuario.

Al guardar, la tarjeta Autenticación protegida usando un token de acceso resume la configuración: un método protegido con OAuth 2.0 ya no acepta auth_key. Guarde el método con Listo y publique la versión.

Bloque Seguridad del método con la tarjeta Autenticación protegida usando un token de acceso

Perfiles: quién puede obtener un token con esos permisos

Los permisos se otorgan a las personas a través de perfiles. En Configuraciones › Cuenta › Perfiles, Agregar Nuevo Perfil pide nombre, descripción, los scopes (solo se listan los que ya usa algún método) y los entornos en los que aplica. Después asigne el perfil a un grupo, desde Cuenta › Grupos › Editar, o a un usuario, desde Cuenta › Usuarios, campo Perfil OAuth. Las aplicaciones de esos desarrolladores quedan autorizadas en el proveedor para pedir tokens con esos permisos.

Modal Agregar Perfil con nombre, descripción, scopes y entornosModal Editar Grupo con el perfil Demo Ventas agregado

Permisos y vigencia del token

  • El token se pide al gateway, en /oauth/token/ del dominio de la API, con grant_type=client_credentials, client_id y client_secret. El gateway reenvía la solicitud al proveedor y devuelve su respuesta.
  • Pida los permisos del método en el parámetro scope; los permisos que el proveedor otorgó vienen en el atributo scope de la respuesta. Un token sin alguno de los permisos del método recibe 403.
  • La vigencia es expires_in, en segundos. Vencido el token, el gateway responde 401 y hay que pedir uno nuevo. Si el método permite refrescar tokens y el proveedor es Keycloak, la respuesta trae además refresh_token, que se canjea en el mismo endpoint con grant_type=refresh_token.
  • Solo las aplicaciones creadas con el proveedor ya configurado tienen client_id y client_secret; si la suya no los muestra, cree una nueva.

Resultado esperado

Con la API Key, el método responde con los datos. Con OAuth 2.0, /oauth/token/ devuelve un access_token con los permisos pedidos y, enviado como Authorization: Bearer, el método responde 200 hasta que el token vence.

Errores frecuentes

ResultadoCausa probableQué revisar
400Solicitud de token incompleta o mal formadaContent-Type, nombres de campos, grant_type y scope.
401Credencial ausente, inválida o vencidaAPI Key o cabecera Authorization; genere un token nuevo si expiró.
401 con "token"El método está protegido con OAuth 2.0 y la solicitud llegó con auth_key o sin cabecera AuthorizationEnvíe Authorization: Bearer con el access token; la auth_key no se acepta en métodos con OAuth 2.0.
403La aplicación no tiene acceso o el scope no alcanzaScopes solicitados al obtener token.
404URL o versión incorrectasDominio, nombre de API, versión, ruta y barra final indicada en la documentación.

Buenas prácticas de seguridad

  • No publique Auth Keys, Client Secrets ni access tokens en documentación, capturas, repositorios o tickets, y guárdelos en un gestor de secretos o en variables de entorno protegidas.
  • No use Client Credentials desde aplicaciones web o móviles donde el secreto pueda quedar expuesto.
  • Solicite el menor conjunto de scopes necesario, renueve el token cuando venza y rote la credencial si sospecha que fue expuesta.

Artículos relacionados