Gateways1 min read

Apigee Integration (Shared Flow)

Deploy the Aforo Shared Flow to your Apigee Organization. Decouple monetization logic from individual API proxies.

Docs  Gateways  Apigee

Task Overview#

JIRA-READY TASK

Deploy the Aforo Shared Flow to your Apigee Organization.

Estimated time: 20 minutes. Target: Platform Architect.

apigee-shared-flow.architectureLIVE

CLIENT

API Request

inbound

Developer App calls Apigee proxy with API key in header.

0ms

PRE-FLOW

Entitlement

PreProxyFlowHook

Shared Flow checks KVM cache for tenant + product entitlement.

<3ms

TARGET

Backend

target endpoint

Request proxied to upstream service. Response captured for metering.

passthrough

POST-FLOW

Metering

PostProxyFlowHook

Async event extraction. Tenant + product + units written to KVM buffer.

0ms added

BUFFER

KVM Batch

every 10s

Apigee KVM aggregates events. Background flush to Aforo ingest.

10s window

EGRESS

Aforo Ingest

ingest.aforo.ai

TLS POST with HMAC signature. Idempotent retry on failure.

<60ms

apigee shared flow → aforo ingest · attached via global flow hook// p95 < 5ms

Why Shared Flow?#

Aforo uses an Apigee Shared Flow to decouple monetization logic from individual API proxies. This means:

One deployment

A single Shared Flow handles metering and entitlements for every proxy in your org

Zero proxy edits

Attach via Flow Hook — no XML edits to individual proxy bundles

Atomic updates

Update Aforo logic once. Every proxy picks it up on the next request.

Full Margin Guard

L1-L3 enforcement runs before traffic reaches your backend target

Prerequisites#

REQUIRED

Apigee X or Apigee Edge

Organization with admin or environment-level deploy rights

REQUIRED

Management API access

Authenticated access to Apigee Management API or Apigee UI console

REQUIRED

Aforo API Key

sk_live_* key from Admin Panel → Settings → API Keys

REQUIRED

KVM permissions

Ability to create or update Key Value Maps in the target environment

Step 1: Import the Shared Flow Bundle#

Download and import the Aforo Shared Flow bundle into your Apigee organization:

terminal

# Download the Aforo Shared Flow bundle
curl -LO https://github.com/aforoai/apigee-shared-flow-aforo-metering/releases/latest/download/aforo-metering-sharedflow.zip

# Import via Management API
curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/sharedflows?action=import&name=aforo-metering" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @aforo-metering-sharedflow.zip

# Deploy to your environment
curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/sharedflows/aforo-metering/revisions/1/deployments" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)"

 INFO

Replace {ORG} with your Apigee organization name and {ENV} with the target environment (e.g., prod, test).

Step 2: Configure the Key Value Map (KVM)#

The Shared Flow reads its configuration from an encrypted KVM. Create the KVM and set the Aforo credentials:

terminal

# Create the KVM (encrypted, environment-scoped)
curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/keyvaluemaps" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aforo-config",
    "encrypted": true
  }'

# Set the API key
curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/keyvaluemaps/aforo-config/entries" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aforo_api_key",
    "value": "sk_live_your_key_here"
  }'

# Set the ingest endpoint
curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/keyvaluemaps/aforo-config/entries" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aforo_ingest_url",
    "value": "https://ingest.aforo.ai/v1/ingest"
  }'

 WARNING

Always use encrypted KVMs for API keys. Apigee encrypts the values at rest and in transit. Never store credentials in proxy-level variables or environment properties.

Step 3: Attach via Flow Hook#

Attach the Shared Flow to a Pre-Proxy Flow Hook for global enforcement. This ensures every API proxy in the environment runs the Aforo entitlement and metering logic automatically — no individual proxy edits.

terminal

# Attach to Pre-Proxy Flow Hook (entitlement check BEFORE backend)
curl -X PUT "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/flowhooks/PreProxyFlowHook" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "sharedFlow": "aforo-metering",
    "continueOnError": false
  }'

# Optional: Also attach to Post-Proxy for async metering
curl -X PUT "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/flowhooks/PostProxyFlowHook" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "sharedFlow": "aforo-metering",
    "continueOnError": true
  }'

PreProxyFlowHook

Entitlement check + Margin Guard enforcement

Before backend

PostProxyFlowHook

Async usage metering + event enrichment

After response

 PRO TIP

Set continueOnError: false on PreProxy to hard-block requests that fail entitlement checks. Set continueOnError: true on PostProxy so metering failures never break the API response.

Margin Guard Enforcement#

The PreProxy Flow Hook executes all three Margin Guard levels before traffic reaches your backend target:

LevelTriggerApigee ActionHTTP Response

L1Margin < 20%JavaScript callout → webhook200 + X-Aforo-Warning header

L2Margin < 10%Assign Message → inject throttle header200 + X-Aforo-Throttle: true

L3Margin < 0%Raise Fault → block request429 Margin Limit Exceeded

 WARNING

L3 enforcement uses Apigee's RaiseFault policy. The request is rejected at the gateway — your backend never sees it. This protects compute costs from unprofitable traffic.

Verification#

Verify the deployment by checking the Flow Hook attachment and sending a test request:

terminal

# Verify Flow Hook is attached
curl -s "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/flowhooks/PreProxyFlowHook" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" | jq .

# Expected: { "sharedFlow": "aforo-metering", "continueOnError": false }

# PaperPlaneTilt a test request through any proxy in the environment
curl -v https://{ORG}-{ENV}.apigee.net/your-api/endpoint \
  -H "X-Tenant-Id: test_tenant_123" \
  -H "Authorization: Bearer sk_live_customer_key"

# Check for Aforo headers in response:
# X-Aforo-Remaining: 8420
# X-Aforo-Plan: enterprise

# Verify event in Aforo
curl -s "https://api.aforo.ai/v1/events?tenant_id=test_tenant_123&limit=1" \
  -H "Authorization: Bearer sk_live_your_admin_key" | jq .

 PRO TIP

If events are not appearing, check the Apigee Debug (Trace) tool. Look for the aforo-metering Shared Flow execution in the PreProxy phase. Common issues: KVM not found (wrong environment), expired Aforo API key, or network policy blocking outbound HTTPS to ingest.aforo.ai.