Saltar al contenido principal

Autenticación OAuth2 en sandbox

Este quickstart muestra cómo obtener un token OAuth2 client_credentials en sandbox y usarlo para consumir APIs protegidas.

Antes de empezar

Necesitas client_id, client_secret y los scopes aprobados para tu integración. Solicítalos a integraciones@aveniocloud.com.

1. Obtener credenciales​

  • Solicita client_id y client_secret al equipo de integraciones.
  • Define los scopes mínimos necesarios para el dominio que quieres consumir (por ejemplo, boletas.read).
  • Audience sugerida: https://api.sandbox.aveniocloud.com.

2. Pedir token client_credentials​

API_BASE="https://api.sandbox.aveniocloud.com"
CLIENT_ID="<tu_client_id>"
CLIENT_SECRET="<tu_client_secret>"
SCOPES="boletas.read"

curl -X POST "$API_BASE/api/v1/auth/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=$SCOPES"

Respuesta (envelope común):

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "expiresIn": 3600,
    "scope": "boletas.read"
  },
  "traceId": "f6b0..."
}

3. Usar el token en otras APIs​

  • Envía el header X-Avenio-Authorization: <accessToken> en cada request.
  • Propaga un solo X-Correlation-Id UUID no vacío en formato N o D. La API lo normaliza a N minúscula; valores inválidos o múltiples se reemplazan y el valor efectivo vuelve en el header de respuesta.

Ejemplo (consulta de operaciones Boletas):

TOKEN="<accessToken>"

curl -X GET "$API_BASE/api/v1/bhe/operaciones/<operationId>" \
  -H "X-Avenio-Authorization: $TOKEN" \
  -H "X-Correlation-Id: 7e9c7c2a-0f56-4c7b-9e5f-8e5b1b98a9b0"

Buenas prácticas​

  • Usa scopes mínimos necesarios por dominio.
  • Rota credenciales ante cualquier sospecha.
  • No expongas client_secret en repositorios o logs.
  • No uses emails, RUT, JWT, bearer tokens ni datos de negocio en X-Correlation-Id.
Producción

Las credenciales y cuotas productivas se habilitan para cada integración. Coordina el paso a producción con ventas@aveniocloud.com.

Cuotas y consumo​

Cada credencial tiene una política independiente de solicitudes por minuto y de cuota mensual. El límite se aplica en el gateway antes de ejecutar la API, para proteger el servicio incluso cuando existan varias réplicas.

Cuando se alcance un límite, la respuesta será 429 Too Many Requests con el envelope estándar y el código API_QUOTA_EXCEEDED. Si aplica al límite por minuto, incluye Retry-After con los segundos de espera. El consumo se mide por API y por período, sin registrar payloads ni secretos.

Última actualización en