API Gateway – Apigee X
Introduction
Apigee X is Google Cloud's next-generation API management platform that enables organizations to design, secure, deploy, monitor, and scale APIs. Unlike its predecessor (Apigee Edge), Apigee X is deeply integrated with Google Cloud infrastructure, leveraging GCP networking, security, and operational tools natively.
Apigee X Architecture Overview
The following architecture illustrates how an API request flows from an API consumer (developer/application) through Apigee X to reach backend services. This is a production-grade setup using F5 as the external load balancer and Private Service Connect (PSC) for secure GCP networking.
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ BACKEND APIs │
│ (On-Premises / AWS / GCP / Azure) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ REST APIs │ │ gRPC │ │ Legacy SOAP │ │ Databases │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────┬───────────────────────────────────────────────────┘
│
│ Southbound (Target Endpoints)
│ (VPN / Cloud Interconnect / Private Access)
▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ GOOGLE CLOUD PLATFORM │
│ │
│ ┌───────────────────────────────────┐ ┌──────────────────────────────────────────┐ │
│ │ CUSTOMER-OWNED GCP PROJECT │ │ GOOGLE-OWNED GCP (Apigee Tenant) │ │
│ │ │ │ │ │
│ │ ┌─────────────────────────────┐ │ │ ┌────────────────────────────────────┐ │ │
│ │ │ Customer VPC │ │ │ │ Apigee VPC │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ ┌───────────────────────┐ │ │ │ │ ┌──────────────────────────────┐ │ │ │
│ │ │ │ │ │ │ │ │ │ GCP Network Bridge │ │ │ │
│ │ │ │ F5 BIG-IP / XC │──┼──┼────┼──┼──│ (VPC Peering / PSC) │ │ │ │
│ │ │ │ (Load Balancer) │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ └──────────────┬───────────────┘ │ │ │
│ │ │ └───────────────────────┘ │ │ │ │ │ Shared VPC │ │ │
│ │ │ │ │ │ │ │ ▼ │ │ │
│ │ │ ▼ │ │ │ │ ┌──────────────────────────────┐ │ │ │
│ │ │ ┌───────────────────────┐ │ │ │ │ │ │ │ │ │
│ │ │ │ Provisioned Apigee │──┼──┼────┼──┼──│ APIGEE X RUNTIME │ │ │ │
│ │ │ │ (Instance Endpoint) │ │ │PSC/│ │ │ │ │ │ │
│ │ │ │ │Peering │ │ │ • API Proxy Execution │ │ │ │
│ │ │ └───────────────────────┘ │ │ │ │ │ • Policy Enforcement │ │ │ │
│ │ │ │ │ │ │ │ • Traffic Management │ │ │ │
│ │ └─────────────────────────────┘ │ │ │ │ • Analytics Collection │ │ │ │
│ │ │ │ │ │ │ │ │ │
│ └───────────────────────────────────┘ │ │ └──────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ └────────────────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────┘ │
│ │ │
└──────────────────────────────────────────────────────────┼──────────────────────────────┘
│
▼
┌────────────────────────┐
│ DEVELOPER PORTAL │
│ (Integrated Portal / │
┌──────────┐ │ Drupal Portal) │
│ Actor │ │ │
│(API Dev/ │ ─── API Request ───► │ • API Documentation │
│Consumer) │ │ • Self-service Keys │
└──────────┘ │ • Try-It Console │
└────────────────────────┘
Architecture Components Explained
1. API Consumer (Actor)
The API consumer is typically an application developer or an external/internal application that needs to access your backend services through managed APIs.
Who are they? - Third-party developers building apps using your APIs - Internal teams consuming microservices - Partner systems integrating with your platform - Mobile/web applications calling your endpoints
What they do: - Register on the Developer Portal to get API keys - Make HTTP/HTTPS requests to published API endpoints - Receive responses processed through Apigee policies
2. Customer-Owned GCP Project
This is YOUR Google Cloud project where you have full control. It contains:
VPC (Virtual Private Cloud): - Your own private network within GCP - Hosts the networking components that connect external traffic to Apigee - Controlled by your security and networking teams
F5 BIG-IP / F5 XC (Distributed Cloud): - Acts as the external-facing load balancer and WAF (Web Application Firewall) - Sits at the edge of your customer VPC - Handles: - SSL/TLS termination - DDoS protection - Geographic load balancing - IP whitelisting/blacklisting - Advanced traffic management (A/B routing, canary deployments) - Layer 7 security (OWASP protection) - Routes clean traffic to the Apigee instance endpoint
Provisioned Apigee (Instance Endpoint): - The Apigee runtime instance that is provisioned within your GCP project - Acts as the bridge between your VPC and Google's managed Apigee infrastructure - Connected to the Apigee runtime via Private Service Connect (PSC) or VPC Peering - This ensures traffic stays within Google's private network (never hits the public internet)
3. Google-Owned GCP (Apigee Tenant)
This is Google's managed infrastructure where the actual Apigee runtime lives. You don't manage this — Google does.
GCP Network Bridge (VPC Peering / PSC): - Provides secure connectivity between your customer VPC and Google's Apigee VPC - Two connection options: - VPC Peering — Direct private connection between VPCs (legacy approach) - Private Service Connect (PSC) — Newer, more secure method using endpoints (recommended) - Traffic never traverses the public internet
Shared VPC: - Google's internal networking layer that connects the network bridge to the Apigee runtime - Managed entirely by Google - Provides redundancy and high availability across zones/regions
Apigee X Runtime: - The core engine where API proxy execution happens - Handles: - Request Processing — Receives API calls, applies policies, routes to backend - Policy Enforcement — Security (OAuth, API keys), rate limiting, caching, transformations - Traffic Management — Load balancing across backend targets, failover - Analytics Collection — Captures metrics, latency, error rates, payload data - Fully managed by Google (auto-scaling, patching, HA)
4. Backend APIs
Your actual services that Apigee proxies requests to:
- On-Premises — Connected via Cloud VPN or Cloud Interconnect
- AWS/Azure — Multi-cloud backends accessible via public endpoints or VPN
- GCP Services — Cloud Run, GKE, Cloud Functions, Compute Engine
- Legacy Systems — SOAP services, mainframes, databases
5. Developer Portal
A self-service web portal for API consumers:
- API Documentation — OpenAPI/Swagger specs rendered as interactive docs
- API Key Management — Developers register apps and get credentials
- Try-It Console — Test API calls directly from the browser
- API Products — Bundled APIs with different access tiers
- Monetization — Usage-based billing for API consumption
Request Flow (End-to-End)
Here's the complete journey of an API request:
Step 1: API Consumer sends HTTPS request
→ hits F5 external load balancer (in Customer VPC)
Step 2: F5 performs:
• SSL termination
• WAF inspection (block attacks)
• Rate limiting at network edge
• Routes to Apigee instance endpoint
Step 3: Request enters Apigee via PSC/VPC Peering
→ traverses Google's private network
→ arrives at Apigee X Runtime
Step 4: Apigee X Runtime processes:
• ProxyEndpoint (request pipeline)
├── Verify API Key / OAuth token
├── Check quota/rate limits
├── Apply threat protection
├── Transform request (if needed)
└── Cache lookup (if configured)
Step 5: Apigee routes to TargetEndpoint
→ request exits Google's network
→ reaches Backend API (on-prem/cloud)
Step 6: Backend processes request and returns response
Step 7: Response flows back through Apigee
• TargetEndpoint (response pipeline)
├── Transform response
├── Apply CORS headers
├── Strip sensitive data
└── Populate cache
Step 8: Response returns through PSC → Customer VPC → F5 → Consumer
Networking Deep Dive
Private Service Connect (PSC) — Recommended
Customer VPC Google-Managed VPC
┌─────────────────┐ ┌─────────────────┐
│ │ │ │
│ PSC Endpoint │ ──────────────►│ Service │
│ (Consumer) │ Private │ Attachment │
│ 10.0.1.5 │ Connection │ (Producer) │
│ │ │ │
└─────────────────┘ └─────────────────┘
Benefits of PSC over VPC Peering: - No IP range conflicts (no overlapping CIDR blocks) - Unidirectional — only consumer can initiate connections - Better security isolation - Can work across organizations - No route table management needed
VPC Peering (Legacy)
Customer VPC (10.0.0.0/16) ←── Peering ──→ Apigee VPC (10.100.0.0/20)
Limitations: - IP ranges must not overlap - Bidirectional access (less secure) - Limited to same organization - Route table complexity grows
Apigee X Components
API Proxies
The fundamental building block — a facade that sits between the consumer and backend:
<!-- Example: apiproxy/proxies/default.xml -->
<ProxyEndpoint name="default">
<PreFlow>
<Request>
<Step><Name>Verify-API-Key</Name></Step>
<Step><Name>Spike-Arrest</Name></Step>
<Step><Name>Quota</Name></Step>
</Request>
</PreFlow>
<Flows>
<Flow name="GetProducts">
<Condition>(proxy.pathsuffix MatchesPath "/products") and (request.verb = "GET")</Condition>
<Request>
<Step><Name>Cache-Lookup</Name></Step>
</Request>
<Response>
<Step><Name>Cache-Populate</Name></Step>
</Response>
</Flow>
</Flows>
<PostFlow>
<Response>
<Step><Name>Add-CORS</Name></Step>
</Response>
</PostFlow>
<HTTPProxyConnection>
<BasePath>/v1/products</BasePath>
</HTTPProxyConnection>
<RouteRule name="default">
<TargetEndpoint>default</TargetEndpoint>
</RouteRule>
</ProxyEndpoint>
Key Policies
| Policy | Category | Purpose |
|---|---|---|
VerifyAPIKey |
Security | Validates API key in request header/query |
OAuthV2 |
Security | Generates/validates OAuth 2.0 tokens |
SpikeArrest |
Traffic | Prevents sudden traffic bursts (e.g., 10ps) |
Quota |
Traffic | Enforces usage limits (e.g., 1000 calls/day) |
ResponseCache |
Performance | Caches backend responses to reduce latency |
AssignMessage |
Mediation | Modify headers, query params, payload |
JSONToXML / XMLToJSON |
Mediation | Format transformation |
JavaCallout |
Extension | Custom Java code for complex logic |
JavaScript |
Extension | Inline JS for lightweight processing |
RaiseFault |
Error Handling | Return custom error responses |
MessageLogging |
Observability | Log to Cloud Logging / external SIEM |
Environments & Deployment
Organization (org)
├── Environment: dev
│ ├── API Proxy: products-api (rev 5)
│ └── API Proxy: orders-api (rev 3)
├── Environment: staging
│ ├── API Proxy: products-api (rev 4)
│ └── API Proxy: orders-api (rev 3)
└── Environment: prod
├── API Proxy: products-api (rev 3) ← stable
└── API Proxy: orders-api (rev 2)
CI/CD Deployment Pipeline
Developer → Git Push → Cloud Build → Deploy to Apigee
# cloudbuild.yaml
steps:
# Lint API proxy
- name: 'node:18'
entrypoint: 'npx'
args: ['apigeelint', '-s', 'apiproxy', '-f', 'table.js']
# Run unit tests
- name: 'node:18'
entrypoint: 'npm'
args: ['test']
dir: 'test'
# Deploy to Apigee X
- name: 'gcr.io/cloud-builders/gcloud'
entrypoint: 'bash'
args:
- '-c'
- |
TOKEN=$(gcloud auth print-access-token)
# Upload API proxy bundle
REV=$(curl -X POST \
"https://apigee.googleapis.com/v1/organizations/$_APIGEE_ORG/apis?name=$_API_NAME&action=import" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @apiproxy.zip | jq -r '.revision')
# Deploy to environment
curl -X POST \
"https://apigee.googleapis.com/v1/organizations/$_APIGEE_ORG/environments/$_APIGEE_ENV/apis/$_API_NAME/revisions/$REV/deployments" \
-H "Authorization: Bearer $TOKEN"
substitutions:
_APIGEE_ORG: 'my-org'
_APIGEE_ENV: 'dev'
_API_NAME: 'products-api'
Security Best Practices
- Use PSC (not VPC Peering) for Apigee connectivity — better isolation
- F5 at the edge — WAF + DDoS protection before traffic hits Apigee
- mTLS everywhere — Between F5 → Apigee and Apigee → Backend
- OAuth 2.0 + API Keys — Layered authentication
- Threat Protection policies — JSON/XML threat protection against injection attacks
- Private backends — Never expose backend APIs to the public internet
- Cloud Armor — Additional GCP-native DDoS protection if not using F5
- Audit logging — Enable Cloud Audit Logs for all Apigee admin operations
Monitoring & Observability
Apigee X integrates with Google Cloud operations:
- Apigee Analytics — API traffic, latency, error rates, developer adoption
- Cloud Monitoring — Infrastructure metrics, alerting
- Cloud Logging — Request/response logs, policy execution logs
- Cloud Trace — Distributed tracing across proxy → backend
Apigee X vs Apigee Edge (Hybrid)
| Feature | Apigee X | Apigee Edge/Hybrid |
|---|---|---|
| Hosting | Fully GCP-managed | Self-managed or hybrid |
| Networking | PSC / VPC Peering | Public internet or VPN |
| Scaling | Automatic | Manual |
| Analytics | Built-in GCP integration | Separate analytics cluster |
| Best For | GCP-native orgs | Multi-cloud / on-prem requirements |
| Cost Model | Pay-per-use | Subscription-based |
API Consumer Authentication & Authorization Flow
This section explains how a consumer (developer/application) securely connects to your API proxies through the Developer Portal, obtains credentials, generates OAuth 2.0 bearer tokens, and makes authorized API calls.
Complete Authentication Architecture
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ DEVELOPER PORTAL │
│ (Integrated / Drupal / Custom Portal) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────────┐ ┌──────────────────┐ ┌────────────────────────────┐ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Developer │ ──(1)──►│ APPS │──(2)───►│ API PRODUCTS │ │ │
│ │ │ Account │ Register│ │Associate│ │ │ │
│ │ │ │ App │ ┌────────────┐ │ │ ┌──────────────────────┐ │ │ │
│ │ └─────────────┘ │ │Consumer Key│ │ │ │ Product: "Payments" │ │ │ │
│ │ │ │Consumer │ │ │ │ │ │ │ │
│ │ │ │Secret │ │ │ │ • payments-api proxy │ │ │ │
│ │ │ └────────────┘ │ │ │ • oauth2-proxy │ │ │ │
│ │ │ │ │ │ • Quota: 1000/day │ │ │ │
│ │ │ ┌────────────┐ │ │ │ • Env: prod │ │ │ │
│ │ │ │ App: │ │ │ └──────────────────────┘ │ │ │
│ │ │ │ "MyApp" │ │ │ │ │ │
│ │ │ │ │ │ │ ┌──────────────────────┐ │ │ │
│ │ │ │ Products: │ │ │ │ Product: "Orders" │ │ │ │
│ │ │ │ [Payments, │ │ │ │ │ │ │ │
│ │ │ │ Orders] │ │ │ │ • orders-api proxy │ │ │ │
│ │ │ └────────────┘ │ │ │ • oauth2-proxy │ │ │ │
│ │ │ │ │ │ • Quota: 5000/day │ │ │ │
│ │ └──────────────────┘ │ │ • Env: prod │ │ │ │
│ │ │ └──────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ └────────────────────────────┘ │ │
│ │ │ │ │
│ └─────────────────────────────────────────────────────────────────────┼──────────────────┘ │
│ │ │
└────────────────────────────────────────────────────────────────────────┼────────────────────┘
│
▼
┌────────────────────────────────┐
│ API PROXIES │
│ │
│ ┌──────────────────────────┐ │
│ │ oauth2-proxy │ │
│ │ /oauth/token │ │
│ │ (Token Generation) │ │
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ payments-api │ │
│ │ /v1/payments │ │
│ │ (OAuthV2 Verify) │ │
│ └──────────────────────────┘ │
│ │
│ ┌──────────────────────────┐ │
│ │ orders-api │ │
│ │ /v1/orders │ │
│ │ (OAuthV2 Verify) │ │
│ └──────────────────────────┘ │
│ │
└────────────────────────────────┘
Step-by-Step Flow
Step 1: Developer Registers on Portal & Creates an App
The developer signs up on the Developer Portal (Integrated Portal, Drupal-based, or a custom-built portal) and creates an application.
Developer ──► Developer Portal ──► Register ──► Create App "MyApp"
│
▼
Portal auto-generates:
• Consumer Key: abc123xyz
• Consumer Secret: secret456def
What happens behind the scenes:
- Apigee creates a Developer entity (email, name, org)
- Apigee creates a DeveloperApp linked to that developer
- A credential pair (Consumer Key + Consumer Secret) is generated
- The app must be associated with one or more API Products
Step 2: App is Associated with API Products
Each API Product defines: - Which API proxies the app can access - Which environments (dev, staging, prod) - Quota limits (e.g., 1000 calls/day) - OAuth scopes allowed - Custom attributes
App: "MyApp"
├── Product: "Payments API"
│ ├── Proxies: [payments-api, oauth2-proxy]
│ ├── Environments: [prod]
│ ├── Quota: 1000 requests/day
│ └── Scopes: [read, write]
│
└── Product: "Orders API"
├── Proxies: [orders-api, oauth2-proxy]
├── Environments: [prod]
├── Quota: 5000 requests/day
└── Scopes: [read]
Step 3: Consumer Generates Bearer Token (OAuth 2.0)
The consumer uses their Consumer Key + Secret to request an access token from the OAuth proxy:
# Token Request (Client Credentials Grant)
curl -X POST https://api.example.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=abc123xyz" \
-d "client_secret=secret456def" \
-d "scope=read write"
Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}
What Apigee does internally:
1. Receives request at oauth2-proxy
2. Validates client_id (Consumer Key) exists
3. Validates client_secret matches
4. Checks the app status is "approved"
5. Identifies which Products are associated with this key
6. Generates an access token and stores the token-to-product mapping
7. Returns the bearer token to the consumer
Step 4: Consumer Makes API Call with Bearer Token
# API Call with Bearer Token
curl -X GET https://api.example.com/v1/payments/txn-001 \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
Step 5: Apigee Validates & Routes the Request
Request arrives at Apigee Runtime
│
▼
┌─────────────────────────────────────────────────────────┐
│ 1. VERIFY OAuth Token │
│ • Is the token valid? (not expired, not revoked) │
│ • Extract: app, developer, products, scopes │
│ │
│ 2. CHECK API Product Authorization │
│ • Is this proxy (payments-api) included in │
│ any product associated with this token? │
│ • Is the request path allowed by the product? │
│ • Is the environment correct? │
│ │
│ 3. ENFORCE Quota │
│ • Check product quota: 1000 requests/day │
│ • Has the app exceeded its limit? │
│ │
│ 4. APPLY Additional Policies │
│ • Spike Arrest (rate limiting) │
│ • Threat Protection (payload inspection) │
│ • Request Transformation (if needed) │
│ │
│ 5. ROUTE to Backend │
│ • Forward request to target endpoint │
│ • https://backend.internal/payments/txn-001 │
└─────────────────────────────────────────────────────────┘
OAuth 2.0 Proxy Configuration
The dedicated OAuth proxy that generates tokens:
<!-- oauth2-proxy/apiproxy/proxies/default.xml -->
<ProxyEndpoint name="default">
<Flows>
<!-- Token Generation Endpoint -->
<Flow name="GenerateToken">
<Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
<Request>
<Step>
<Name>Generate-Access-Token</Name>
</Step>
</Request>
</Flow>
<!-- Token Refresh Endpoint -->
<Flow name="RefreshToken">
<Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
<Request>
<Step>
<Name>Refresh-Access-Token</Name>
</Step>
</Request>
</Flow>
<!-- Token Revocation -->
<Flow name="RevokeToken">
<Condition>(proxy.pathsuffix MatchesPath "/revoke") and (request.verb = "POST")</Condition>
<Request>
<Step>
<Name>Revoke-Access-Token</Name>
</Step>
</Request>
</Flow>
</Flows>
<HTTPProxyConnection>
<BasePath>/oauth</BasePath>
</HTTPProxyConnection>
<!-- No backend needed — Apigee handles token generation internally -->
<RouteRule name="noTarget"/>
</ProxyEndpoint>
OAuthV2 Policy — Generate Token:
<!-- policies/Generate-Access-Token.xml -->
<OAuthV2 name="Generate-Access-Token">
<Operation>GenerateAccessToken</Operation>
<ExpiresIn>3600000</ExpiresIn> <!-- 1 hour in ms -->
<SupportedGrantTypes>
<GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
<GenerateResponse enabled="true"/>
</OAuthV2>
Resource Proxy with Token Verification
The actual API proxy that verifies the token before routing:
<!-- payments-api/apiproxy/proxies/default.xml -->
<ProxyEndpoint name="default">
<PreFlow>
<Request>
<!-- Step 1: Verify the Bearer Token -->
<Step>
<Name>Verify-OAuth-Token</Name>
</Step>
<!-- Step 2: Check Quota (auto-resolved from product) -->
<Step>
<Name>Enforce-Product-Quota</Name>
</Step>
<!-- Step 3: Spike Arrest -->
<Step>
<Name>Spike-Arrest</Name>
</Step>
</Request>
</PreFlow>
<HTTPProxyConnection>
<BasePath>/v1/payments</BasePath>
</HTTPProxyConnection>
<RouteRule name="default">
<TargetEndpoint>default</TargetEndpoint>
</RouteRule>
</ProxyEndpoint>
OAuthV2 Policy — Verify Token:
<!-- policies/Verify-OAuth-Token.xml -->
<OAuthV2 name="Verify-OAuth-Token">
<Operation>VerifyAccessToken</Operation>
</OAuthV2>
After verification, Apigee populates flow variables:
accesstoken.{token_name}.client_id → abc123xyz
accesstoken.{token_name}.developer.email → dev@example.com
accesstoken.{token_name}.app.name → MyApp
accesstoken.{token_name}.scope → read write
apiproduct.name → Payments API
Quota Policy (product-driven):
<!-- policies/Enforce-Product-Quota.xml -->
<Quota name="Enforce-Product-Quota">
<Distributed>true</Distributed>
<Synchronous>true</Synchronous>
<!-- Values auto-resolved from API Product configuration -->
<Allow countRef="apiproduct.developer.quota.limit" count="1000"/>
<Interval ref="apiproduct.developer.quota.interval">1</Interval>
<TimeUnit ref="apiproduct.developer.quota.timeunit">day</TimeUnit>
<Identifier ref="client_id"/>
</Quota>
Entity Relationships
┌──────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ DEVELOPER │ │ DEVELOPER APP │ │ API PRODUCT │
│ │ 1───N │ │ N───N │ │
│ • email │───────│ • App Name │───────│ • Product Name │
│ • name │ │ • Consumer Key │ │ • API Proxies [] │
│ • org │ │ • Consumer Secret│ │ • Environments [] │
│ • status │ │ • Products [] │ │ • Quota Limit │
│ │ │ • Status │ │ • Scopes [] │
│ │ │ • Key Expiry │ │ • Access: public/ │
│ │ │ │ │ private/internal │
└──────────────┘ └──────────────────┘ └──────────┬──────────┘
│
N────┼────N
│
┌─────────▼──────────┐
│ API PROXY │
│ │
│ • Proxy Name │
│ • BasePath │
│ • Target Backend │
│ • Policies │
│ • Revision │
└─────────────────────┘
Supported OAuth 2.0 Grant Types
| Grant Type | Use Case | Flow |
|---|---|---|
| Client Credentials | Server-to-server (no user context) | App sends key+secret → gets token |
| Authorization Code | User-facing apps (most secure) | User login → auth code → token exchange |
| Password (ROPC) | Trusted first-party apps | Username+password+key+secret → token |
| Implicit | Legacy SPAs (deprecated) | Redirect → token in URL fragment |
Client Credentials Flow (Most Common for APIs)
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Consumer │ │ OAuth Proxy │ │ API Proxy │
│ (App) │ │ /oauth/token │ │ /v1/payments │
└────┬─────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ POST /oauth/token │ │
│ grant_type=client_credentials │ │
│ client_id=abc123 │ │
│ client_secret=secret456 │ │
│────────────────────────────────►│ │
│ │ │
│ │ Validate credentials │
│ │ Check app status │
│ │ Resolve products │
│ │ Generate token │
│ │ │
│◄────────────────────────────────│ │
│ {"access_token": "eyJ...", │ │
│ "expires_in": 3600} │ │
│ │ │
│ GET /v1/payments/txn-001 │ │
│ Authorization: Bearer eyJ... │ │
│─────────────────────────────────┼──────────────────────────────────►│
│ │ │
│ │ Verify token │
│ │ Check product access │
│ │ Enforce quota │
│ │ Route to backend │
│ │ │
│◄────────────────────────────────┼───────────────────────────────────│
│ 200 OK {"payment": {...}} │ │
│ │ │
Error Scenarios
| Scenario | HTTP Code | Error |
|---|---|---|
| Invalid Consumer Key | 401 | InvalidApiKey |
| Invalid Consumer Secret | 401 | InvalidClientCredentials |
| Expired Token | 401 | access_token_expired |
| Revoked Token | 401 | access_token_revoked |
| Proxy not in Product | 403 | InvalidApiProductAccess |
| Quota Exceeded | 429 | QuotaViolation |
| App not approved | 401 | DeveloperAppNotApproved |
Portal Types
| Portal | Description | Best For |
|---|---|---|
| Integrated Portal | Built-in Apigee portal (Apigee-managed) | Quick setup, small teams |
| Drupal Portal | Open-source CMS-based portal (Apigee module) | Full customization, large enterprises |
| Custom Portal | Build your own using Apigee Management APIs | Unique branding, existing portals |
All portals interact with Apigee's Management API to create developers, apps, and retrieve credentials.