Bearer salvo que el método lo solicite expresamente.auth_key a la URL:GET https://api.example.com/accounts/v1/accounts.json?auth_key=YOUR_AUTH_KEY
Authorization con la llave como valor:curl --request GET \
--header 'Authorization: YOUR_AUTH_KEY' \
'https://api.example.com/accounts/v1/accounts.json'
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.
/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'
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"
}Authorization con el prefijo Bearer:curl --request GET \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
'https://api.example.com/accounts/v1/accounts.json/'
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.
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:
00d 00h 00m 00s, máximo 30 días. Con Keycloak rige la vigencia de la integración de la cuenta.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.
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.
/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.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.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.client_id y client_secret; si la suya no los muestra, cree una nueva.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.
| Resultado | Causa probable | Qué revisar |
|---|---|---|
| 400 | Solicitud de token incompleta o mal formada | Content-Type, nombres de campos, grant_type y scope. |
| 401 | Credencial ausente, inválida o vencida | API 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 Authorization | Envíe Authorization: Bearer con el access token; la auth_key no se acepta en métodos con OAuth 2.0. |
| 403 | La aplicación no tiene acceso o el scope no alcanza | Scopes solicitados al obtener token. |
| 404 | URL o versión incorrectas | Dominio, nombre de API, versión, ruta y barra final indicada en la documentación. |