Apigee Integration (Shared Flow)

Task Overview#

Why Shared Flow?#

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

Prerequisites#

One-Click Install from Aforo#

If your Apigee organization is already connected under Governance → Integrations, you don't need Steps 1–3. Open the connection, turn on metering and deploy. Aforo runs the same Management API calls you would:

Deploy again after changing a setting: the KVM is refreshed every time, and the flow picks the change up within five minutes (it caches KVM reads for 300 seconds). Removing metering detaches the hook, undeploys the flow and deletes the entries Aforo wrote. The shared flow is deleted once no environment has it deployed.

One-click install uses the Apigee X and hybrid Management API. It does not cover Apigee Edge; follow the manual steps below there. The rest of this page is the same install by hand.

Step 1: Import the Shared Flow Bundle#

The shared flow lives in the Aforo SDK distribution repo at aforo-gateway-plugins/apigee/. There is no public registry release, so deploy from source — the apigee/sharedflowbundle/ folder is the source of truth, and apigeecli zips and imports it for you:

# Clone the SDK distribution repo and enter the Apigee plugin folder
git clone https://github.com/aforoai/SDKs.git
cd SDKs/aforo-gateway-plugins/apigee

# Create the shared flow from the bundle folder
apigeecli sharedflows create bundle \
  --name aforo-metering \
  --folder sharedflowbundle \
  --org "$APIGEE_ORG" \
  --token "$(gcloud auth print-access-token)"

# Deploy the imported revision to your environment
apigeecli sharedflows deploy \
  --name aforo-metering \
  --rev 1 \
  --env "$APIGEE_ENV" \
  --org "$APIGEE_ORG" \
  --token "$(gcloud auth print-access-token)"

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:

# Create the KVM (encrypted, organization-scoped — the bundle reads it at org level)
curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/keyvaluemaps" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aforo-metering-config",
    "encrypted": true
  }'

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

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

# Set the workspace (tenant) id
curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/keyvaluemaps/aforo-metering-config/entries" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "tenant_id", "value": "your-workspace-id" }'

Step 3: Attach via Flow Hook#

Attach the Shared Flow to the environment's Post-Proxy Flow Hook. Every API proxy in the environment then sends a usage event after its response is built — no individual proxy edits. The flow reads the response status, so it belongs on the response path; it can't run in PostClientFlow, which accepts only FlowCallout, MessageLogging and ServiceCallout policies.

# Attach to the Post-Proxy Flow Hook (metering, after the backend responds)
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
  }'

How Calls Get an Outcome#

Read this if any rate plan behind this gateway uses Outcome-Based pricing — it bills each call at a weight for its executionStatus. Every other pricing model ignores the field. The plugin sets it from the upstream response status:

Override the status for specific codes

When the default table is wrong for your API — say a 404 is a normal answer, not a failure — map exact codes with the status_outcomes entry in the aforo-metering-config KVM. Format: comma-separated code=STATUS pairs:

curl -X POST "https://apigee.googleapis.com/v1/organizations/{ORG}/keyvaluemaps/aforo-metering-config/entries" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "status_outcomes", "value": "404=SUCCESS,429=ERROR" }'

Keys are exact HTTP codes from 200 to 599. Values must be one of the 11 statuses: SUCCESS, PARTIAL, TIMEOUT, ERROR, VALIDATION_FAILED, FAILED, FAILURE, CANCELLED, PENDING, BLOCKED, HITL_REQUIRED. Invalid entries are ignored without a warning. If a code is listed twice, the last valid entry wins. An override can't give a status to a missing, 0 or 1xx code.

Requests that aren't metered

By default, responses with status 401, 403 or 429 and requests to /health, /ready or /metrics produce no event at all — they cost nothing whatever the rate plan says. All five gateway plugins share this default. A path is skipped when it equals an entry or starts with it, so /health also covers /health/live.

Leave an entry out to get its default. A KVM entry can't be stored empty, which is why metering everything takes the word none. KVM reads are cached for five minutes. Entries that aren't whole numbers from 100 to 599 are ignored. A list you set replaces the default rather than adding to it: a status list of 404,500 skips only those two and starts metering 401, 403 and 429. A status you choose to meter bills as BLOCKED unless you override it above.

Margin Guard Enforcement#

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

Verification#

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

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

# Expected: { "flowHookPoint": "PostProxyFlowHook", "sharedFlow": "aforo-metering", "continueOnError": true }

# Verify the revision is deployed (state should be READY)
curl -s "https://apigee.googleapis.com/v1/organizations/{ORG}/environments/{ENV}/sharedflows/aforo-metering/deployments" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" | jq .

# 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

# Then confirm it arrived: in Aforo, open Intelligence → Usage Ingestion.
# The event shows up once the plugin has sent it (batching plugins flush every few seconds).