Allegro API Gateway

High-Level Request Flow

The following describes how an API call flows through the Allegro API Gateway:

1. The external client sends an API call to the gateway. The gateway accepts two credential shapes:
   • Authorization: Bearer <JWT>—the partner manages their own Keycloak token lifecycle.
   • X-Allegro-API-Key: pak_…—the partner exchanges credentials for a long-lived API key via /partner/session/login; the gateway refreshes the underlying Keycloak token internally.
2. NGINX Ingress enforces rate limiting and payload size limits.
3. The Allegro API Gateway performs JWT validation, partner session resolution, per-partner authorization, request validation, and circuit breaking.
4. The gateway translates the REST request into a GraphQL request and forwards it to the appropriate Allegro service:
   • Allegro Core service for core APIs
   • Allegro Mediation service for mediation APIs
   • Allegro Operations service for job scheduling operations

Key Features

The Allegro API Gateway handles the following functions:

Request Validation

The Allegro API Gateway validates all incoming POST, PUT, and PATCH requests. The following table describes the validation rules and the HTTP status code each rule returns on failure.

GET and DELETE requests, and public endpoints (/q/*, /swagger-ui/*, /openapi), are not subject to these validations.

Circuit Breaking and Fault Tolerance

The GraphQLClient uses SmallRye Fault Tolerance (MicroProfile) to protect against backend failures. The following table describes each mechanism and its behavior.

The OkHttp client also enforces the following timeouts: connect timeout of 10 seconds, read timeout of 30 seconds, and write timeout of 10 seconds.

Rate Limiting

Rate limiting is enforced at the NGINX Ingress layer. The following table lists the default values.

When a client exceeds these limits, the gateway returns 429 Too Many Requests. You can override the default values for a specific environment in the corresponding YAML file. The following example shows sample NGINX ingress annotations:

ingress:
  annotations:
    nginx.ingress.kubernetes.io/limit-rps: "50"
    nginx.ingress.kubernetes.io/limit-rpm: "1500"

Authentication

The Allegro API Gateway uses quarkus-oidc in service mode (bearer-only; no login redirects). On startup, the gateway fetches Keycloak’s JWKS public keys from:

{KEYCLOAK_URL}/realms/{KEYCLOAK_REALM}/protocol/openid-connect/certs

Every request to an API endpoint must carry either Authorization: Bearer <token> or X-Allegro-API-Key: pak_…. The gateway validates the bearer token locally—without a network call per request—checking the signature against cached JWKS, expiry, and issuer. Tokens that are invalid, expired, from the wrong issuer, or missing receive 401 Unauthorized immediately.

Partner Session Brokerage

Partners that do not want to manage Keycloak token rotation can exchange short-lived credentials for a long-lived opaque API key. The following table describes the available session operations.

After login, include the API key in the X-Allegro-API-Key header on every API call. The gateway resolves the key to a live access token, refreshing it from Keycloak as needed, and forwards only the validated bearer token to backend services. Store your API key in a secrets manager (such as Vault or AWS Secrets Manager) and never commit it to source control.

Per-Partner Authorization

After authentication, the gateway checks every request against a partner-specific path allow-list before forwarding it to a hub controller. Authorization relies on two sources of truth:

Roles follow the naming convention allegro:profile:<profile-name>. The following example shows sample profile definitions:

profiles:
  full-access:
    allowedPaths: ["*"]
  customer-billing:
    allowedPaths: ["/customer", "/billing", "/balance", "/common"]
  read-only:
    allowedPaths: ["/customer", "/pricing", "/billing", "/balance", "/common"]
  deny-all:
    allowedPaths: []

defaultProfile: deny-all

At request time, the PartnerAuthorizationFilter reads the partner’s roles, identifies the allegro:profile: role, looks up the corresponding profile in the YAML, and returns 403 if the request path is not in the profile’s allowedPaths. Path matching is segment-aware: /customer matches /customer/account/123 but not /customers. Partners with no allegro:profile:* role fall through to deny-all.

Partner Onboarding

The following describes the end-to-end process for onboarding a new partner to the Allegro API Gateway.

# Password grant (interactive partner)
curl -X POST https://api.allegro.example.com/partner/session/login \
  -H "Content-Type: application/json" \
  -d '{
    "grantType": "password",
    "username": "partner-acme-svc",
    "password": "***"
  }'

# Client credentials grant (machine-to-machine)
curl -X POST https://api.allegro.example.com/partner/session/login \
  -H "Content-Type: application/json" \
  -d '{
    "grantType": "client_credentials",
    "clientId": "partner-acme-app",
    "clientSecret": "***"
  }'

{
  "apiKey": "pak_xJ9k...",
  "sessionExpiresAt": "2026-05-14T03:30:00Z",
  "header": "X-Allegro-API-Key",
  "note": "Treat the apiKey as a long-lived credential. Subsequent calls carry it in the header above."
}

ACCESS=$(jq -r '.apiKey' login-response.json)

# Read endpoint
curl https://api.allegro.example.com/customer/account/123 \
  -H "X-Allegro-API-Key: $ACCESS"

# Mutating endpoint
curl -X POST https://api.allegro.example.com/customer/account \
  -H "X-Allegro-API-Key: $ACCESS" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Jane", "lastName": "Doe", ... }'

# Introspect
curl https://api.allegro.example.com/partner/session \
  -H "X-Allegro-API-Key: $ACCESS"

# Revoke (idempotent, returns 204)
curl -X DELETE https://api.allegro.example.com/partner/session \
  -H "X-Allegro-API-Key: $ACCESS"