API Management Platform Design: [Organisation or platform name]
Design for the platform that publishes, secures, governs and measures
an organisation's APIs as products: the API product model, consumer
segments and onboarding, gateway topology (edge, internal, partner and
service mesh), security policies (OAuth 2.0, mutual TLS, sender-constrained
tokens, API keys), rate plans and quotas, the developer portal,
contract, versioning and lifecycle, analytics, monetisation, APIOps
delivery, availability and the operating model. Contracts follow the
OpenAPI Specification 3.2; security follows the OAuth 2.0 Security Best
Current Practice (RFC 9700) and, for financial-grade APIs, the FAPI 2.0
Security Profile. Replace every [bracketed] value and every row
marked Example.
Document control
| Field | Value |
|---|
| Document ID | [APIM-001] |
| Platform name | [Name] |
| Gateway and portal products | [Product names and versions] |
| Identity provider and authorisation server | [Product] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@api-platform-lead] |
| Approvers/reviewers | [@chief-architect], [@security-architect], [@api-product-manager], [@network-lead] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related documents | [Integration strategy], [API design guidelines], [Security architecture] |
Approvals
| Role | Name | Decision | Date |
|---|
| Platform owner | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| API product management | [@name] | [Decision] | YYYY-MM-DD |
| Network | [@name] | [Decision] | YYYY-MM-DD |
| Architecture board | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | Example: Approved; edge and internal gateways, portal for partners |
| 1.1 | YYYY-MM-DD | [@name] | Example: Added DPoP sender-constrained tokens for partner write APIs |
Contents
1. Scope, drivers and context
1.1 Drivers
| ID | Driver | Platform implication |
|---|
| AMD-001 (Example) | Partners need self-service access to product and stock data | Developer portal with sign-up, sandbox and keys |
| AMD-002 (Example) | Security audit found inconsistent authentication across APIs | Central policy enforcement at the gateway |
| AMD-003 (Example) | Business wants to charge marketplaces for high-volume access | Rate plans, metering and billing export |
| AMD-004 (Example) | Mobile app traffic peaks at ten times normal during sales | Elastic edge gateway with caching |
| [AMD-NNN] | [Driver] | [Implication] |
1.2 Scope
| In scope | Out of scope |
|---|
| Example: All APIs consumed outside the owning domain | Calls inside one domain, which use the service mesh only |
| Example: Partner and public APIs, channel APIs | Event streams (see Event-Driven Architecture Design, architecture/event-driven-architecture-design) |
| Example: Outbound calls to third-party APIs through an egress gateway | B2B and EDI (see B2B, EDI and File Transfer Design, architecture/b2b-edi-file-transfer-design) |
| [Item] | [Item] |
1.3 Context
The platform sits between consumers and the experience, process and
system APIs defined in the Integration Strategy (architecture/integration-strategy).
2. API product model
| Product ID | Product name | Operations included | Audience | Owner | Plans | Status |
|---|
| APP-001 (Example) | Catalogue | GET products, GET prices, GET categories | Partner, Public | @pm-catalogue | Free, Partner, Premium | Published |
| APP-002 (Example) | Stock availability | GET stock by SKU and location | Partner | @pm-stock | Partner, Premium | Published |
| APP-003 (Example) | Order placement | POST orders, GET order status | Marketplace partners | @pm-order | Partner write | Beta |
| APP-004 (Example) | Store operations | Internal process APIs for store systems | Internal | @team-store | Internal | Published |
| [APP-NNN] | [Name] | [Operations] | [Audience] | [@owner] | [Plans] | [Status] |
Every product has a product page with: purpose and use cases, the
OpenAPI document, authentication method, plans and limits, service
level, change log, deprecation status and a support channel. The product
owner decides what the product contains and approves breaking changes;
the API owning team builds and runs the backend.
3. Consumer segments and onboarding
| Segment | Trust level | Onboarding path | Credential | Contract | Support |
|---|
| First-party channels (Example) | High | Platform team registers the client | OAuth 2.0 client with authorisation code and PKCE for users | Internal | Platform on-call |
| Contracted partners (Example) | Medium to high | Portal request, business approval, legal agreement, security review | Confidential OAuth 2.0 client, private key JWT or mutual TLS authentication | Partner agreement and data processing terms | Named partner manager |
| Public developers (Example) | Low | Self-service sign-up, email verification, terms acceptance | API key for read-only public data, OAuth 2.0 for user data | Online terms of use | Community forum |
| Internal teams (Example) | High | Catalogue request with consumer details | Workload identity, OAuth 2.0 client credentials | Internal | Platform office hours |
| [Segment] | [Trust] | [Path] | [Credential] | [Contract] | [Support] |
Onboarding acceptance criteria for partners: agreement signed; security
questionnaire approved (Supplier Security Assessment,
compliance/supplier-security-assessment); sandbox tests passed;
production client created with least-privilege scopes; contacts for
incidents recorded.
4. Gateway topology
| Tier | Placement | Traffic | Responsibilities | Not responsible for |
|---|
| Web application firewall and CDN (Example) | Internet edge | All public traffic | DDoS protection, bot management, TLS termination, static caching | API authorisation |
| Edge API gateway (Example) | Perimeter network, two regions | External consumers | Token validation, scopes, quotas, schema validation, response caching, analytics | Business orchestration |
| Internal API gateway (Example) | Private network | Cross-domain internal calls | Token validation, quotas per consumer, routing, analytics | Internet-facing threats |
| Service mesh (Example) | Inside each cluster | Calls within a domain | Mutual TLS between workloads, retries, service-level telemetry | Consumer plans, portal |
| Egress gateway (Example) | Private network | Outbound third-party calls | Allow list of destinations, credential injection, egress logging | Inbound traffic |
| [Tier] | [Placement] | [Traffic] | [Responsibilities] | [Not responsible] |
Topology decisions to record in ADRs: managed or self-hosted control
plane; self-hosted gateway runtimes close to on-premises backends;
single or multiple gateway products; where policy definitions are
stored; and whether the internal gateway is needed at all where the mesh
already enforces identity.
5. Security policies
5.1 Baseline policies on every API
| ID | Policy | Rule |
|---|
| SEC-001 | Transport | TLS 1.2 or later, TLS 1.3 preferred; HSTS on public hosts |
| SEC-002 | Authentication | OAuth 2.0 access tokens validated at the gateway (signature, issuer, audience, expiry); API keys only where SEC-007 allows |
| SEC-003 | Grants | Authorisation code with PKCE for user-facing clients; client credentials for machine clients; implicit and password grants not allowed |
| SEC-004 | Scopes | Scopes per product and operation class (read, write, admin); least privilege at subscription time |
| SEC-005 | Input validation | Request validated against the OpenAPI schema; payload size limits; reject unknown content types |
| SEC-006 | Errors | Problem details format (RFC 9457) without stack traces or internal hostnames |
| SEC-007 | API keys | Allowed only for read-only public data, combined with quotas; never sent in URLs |
| SEC-008 | Logging | Token identifiers and client IDs logged; tokens, secrets and personal data never logged |
| SEC-009 | Threat protection | Protection against the risks in the OWASP API Security Top 10 checked in design review |
5.2 Extra policies by risk class
| Risk class | Examples | Extra policies |
|---|
| Class 1, public read (Example) | Catalogue | Quotas, caching, bot protection |
| Class 2, partner data (Example) | Stock, order status | Confidential clients with private key JWT or mutual TLS client authentication; IP allow list optional |
| Class 3, writes and personal data (Example) | Order placement, customer profile | Sender-constrained access tokens (mutual TLS per RFC 8705 or DPoP per RFC 9449); short token lifetime; step-up for sensitive actions |
| Class 4, financial-grade (Example) | Payment initiation, account data | Full FAPI 2.0 Security Profile: pushed authorisation requests, PKCE with S256, sender-constrained tokens, confidential clients only; see Open Banking API Design (industry/open-banking-api-design) |
5.3 Credential lifecycle
| Item | Rule (Example) |
|---|
| Client secret | Avoided for class 2 and above; replaced by private key JWT or mutual TLS |
| Client certificate | Issued by the approved CA (PKI and Certificate Architecture, security/pki-certificate-architecture); maximum validity per CA policy; renewal alert at 30 days |
| Access token lifetime | 5 to 15 minutes by class |
| Refresh token | Rotated on use, bound to the client; not issued to machine clients |
| API key | Rotated yearly or on suspicion; old key valid for 7 days after rotation |
| Revocation | Portal action and emergency runbook; gateway honours revocation within [5 minutes] |
6. Traffic management, rate plans and quotas
| Plan | Products | Rate limit | Quota | Burst | Price | Behaviour at limit |
|---|
| Free (Example) | APP-001 | 5 requests per second per app | 10,000 per day | 10 | None | HTTP 429 with Retry-After |
| Partner (Example) | APP-001, APP-002 | 50 per second per app | 1,000,000 per month | 100 | Included in agreement | HTTP 429; alert to partner manager at 80 % |
| Premium (Example) | APP-001, APP-002 | 200 per second per organisation | 10,000,000 per month | 400 | [USD 2,000 per month] | Overage billed at [USD 0.10 per 1,000 calls] |
| Partner write (Example) | APP-003 | 20 per second per app | 200,000 per month | 40 | Included | HTTP 429 |
| Internal (Example) | APP-004 | 500 per second per consumer | None | 1,000 | Showback | HTTP 429, page on-call |
Backend protection: each backend declares a safe capacity; the gateway
applies a global spike arrest at [80 %] of it, independent of plans.
Rate limit headers follow the API Design Guidelines. Response caching is
allowed for class 1 GET operations with explicit cache keys and a
maximum time to live of [60 seconds] for stock data.
7. Developer portal
| Capability | Requirement |
|---|
| Discovery | Search and browse products by audience and domain; product pages from section 2 |
| Documentation | Reference rendered from the OpenAPI document; guides, tutorials and code samples in the portal repository |
| Try it | Interactive console against the sandbox with sandbox credentials only |
| Sandbox | Synthetic data, same contract as production, reset nightly |
| Self-service | Sign-up, team management, app registration, key and certificate upload, subscription requests |
| Change communication | Change log per product; deprecation notices; subscription to change emails or feed |
| Status | Link to the status page and incident history |
| Support | Forum, ticket form for partners, response targets per segment |
| Accessibility | Portal conforms to WCAG 2.2 level AA |
| Analytics for consumers | Usage, errors and quota consumption per app |
Target: a public developer makes a first successful sandbox call within
[15 minutes] of sign-up; a partner reaches production within [10
working days] including approvals.
8. Contracts, versioning and lifecycle
| Area | Rule |
|---|
| Contract format | OpenAPI Specification 3.2 for new APIs (3.1 accepted for existing APIs); linted against the house rule set in CI |
| Source of truth | Contract in the API repository; gateway configuration and portal pages generated from it |
| Versioning | Major version in the path (/v1/); minor and patch changes must be backward compatible |
| Breaking change | New major version; both versions run in parallel for at least [12 months] for partners |
| Deprecation signalling | Deprecation header (RFC 9745) and Sunset header (RFC 8594) on deprecated operations; notice in portal and email |
| Retirement | After the sunset date, return HTTP 410 for [30 days], then remove the route |
| Policy | API Deprecation Policy (architecture/api-deprecation-policy) governs notice periods |
These states are the portal view of the integration catalogue lifecycle
in the Integration Strategy (architecture/integration-strategy, section
10.2): Design maps to Proposed, Beta maps to Designed (contract reviewed,
sandbox only), and Published, Deprecated and Retired keep their names.
9. Analytics and observability
| Audience | Measures | Source |
|---|
| Operations | Request rate, error rate by status class, latency 50th, 95th and 99th percentile (gateway and backend split), saturation, certificate expiry | Gateway metrics and traces |
| Product owners | Active apps, calls per product, top consumers, adoption of new versions, time to first call, churned apps | Analytics store |
| Consumers | Own usage, errors and quota consumption | Portal |
| Security | Authentication failures, scope denials, unusual traffic per client, blocked requests | Gateway logs to SIEM |
| Finance | Billable calls per plan and organisation | Metering export |
Every request carries a correlation ID and W3C Trace Context headers
from the gateway to the backend. Analytics data that contains personal
data follows the retention rules in the privacy notice.
10. Monetisation
| Decision | Choice (Example) |
|---|
| Pricing model | Subscription tiers with included calls and metered overage |
| Billable unit | Successful calls (HTTP 2xx) to billable operations; errors caused by the platform not billed |
| Metering source | Gateway transaction log, not sampled analytics |
| Rating | Monthly aggregation per organisation and plan |
| Billing integration | Daily usage export to the billing system; invoices issued by finance |
| Disputes | Partners can download usage detail per day from the portal |
| Tax and contracts | Owned by finance and legal |
For the rating and billing pipeline in depth, use SaaS Metering and
Billing Design (architecture/saas-metering-billing-design).
11. APIOps delivery
| Stage | Automated checks |
|---|
| Pull request on API repository | OpenAPI lint, breaking change detection against the published version, security rule set, spelling of descriptions |
| Build | Generate gateway configuration and portal pages from the contract; contract tests against a mock |
| Deploy to non-production | Apply configuration through the platform API; smoke tests; security scan of the API |
| Approve | Product owner for new products; security for class 3 and 4 |
| Deploy to production | Same artefact; canary or blue and green on the gateway; automatic rollback on error rate rise |
Environments: development, test, sandbox (consumer facing), production.
Configuration differences between environments are parameters only.
12. Availability, capacity and recovery
| Input | Value (Example) |
|---|
| Average traffic | 1,200 requests per second |
| Peak traffic (sale events) | 12,000 requests per second |
| Gateway capacity per instance at target latency | 1,500 requests per second |
| Instances needed at peak, per region | Each region must carry the full peak if the other region fails: 12,000 / 1,500 = 8; to survive one zone loss as well, 8 must remain in two zones, so 4 per zone x 3 zones = 12 per region, 24 in two regions |
| Added gateway latency budget | 10 ms at the 95th percentile |
| Concern | Design |
|---|
| Availability target | 99.95 % for the edge gateway per month |
| Zones and regions | Three zones per region; active and active in two regions behind global load balancing |
| Control plane outage | Data plane keeps serving with cached configuration; no deployments until restored |
| Authorisation server outage | Gateways validate signed tokens locally with cached keys; new token issuance fails, so token lifetimes and refresh behaviour are set accordingly |
| Analytics outage | Requests continue; logs buffered locally for [24 hours] |
| Recovery | Configuration restored from the repository; tested twice a year |
13. Operating model
| Activity | Platform team | API product owner | Domain team | Security | Partner management |
|---|
| Gateway and portal operation | A, R | I | I | C | I |
| Policy templates | A, R | C | C | C | I |
| API contract and backend | C | A | R | C | I |
| Product definition and plans | C | A, R | C | I | C |
| Partner onboarding approval | I | A | I | R | R |
| Security review of class 3 and 4 APIs | C | C | R | A | I |
| Incident on gateway | A, R | I | C | C | I |
| Incident on backend | C | I | A, R | C | I |
Service levels between the platform and domain teams: new API onboarded
to the gateway within [2 working days] of an approved contract; policy
template change requests answered within [5 working days].
14. Risks and decisions
| ID | Type | Description | Response | Owner |
|---|
| RSK-001 (Example) | Risk | Gateway product lock-in through proprietary policy language | Keep policies simple and generated; store contracts in OpenAPI; exit plan in ADR | @api-platform-lead |
| RSK-002 (Example) | Risk | Partner credentials leaked in public code repositories | Secret scanning partnership, short-lived tokens, sender-constrained tokens for writes | @security-architect |
| RSK-003 (Example) | Risk | Shadow APIs exposed without the gateway | Network rules allow inbound internet traffic only through the edge tier; discovery scans | @network-lead |
| DEC-001 (Example) | Decision | Managed control plane with self-hosted data plane in the data centre | ADR-APIM-001 | @api-platform-lead |
| DEC-002 (Example) | Decision | DPoP for partner write APIs where clients cannot manage certificates | ADR-APIM-002 | @security-architect |
| [ID] | [Type] | [Description] | [Response] | [@owner] |
15. Glossary and references
15.1 Glossary
| Term | Meaning |
|---|
| API product | Bundle of operations, plans and documentation offered to consumers |
| Plan | Set of limits, quotas and price attached to a subscription |
| Data plane | Gateway runtime that processes API traffic |
| Control plane | Management service that configures gateways and the portal |
| Sender-constrained token | Access token bound to a key held by the client, so a stolen token cannot be replayed by another party |
| DPoP | Demonstrating Proof of Possession, an application-level method of sender-constraining tokens |
| PKCE | Proof Key for Code Exchange, protection of the authorisation code flow |
| PAR | Pushed Authorization Requests, sending authorisation parameters directly to the server |
| APIOps | Managing API definitions and platform configuration as code through pipelines |
15.2 References
| Reference | Version or date checked | Use |
|---|
| OpenAPI Specification, spec.openapis.org | 3.2 (3.2.0 September 2025, 3.2.1 September 2026) | Contracts |
| RFC 9700, Best Current Practice for OAuth 2.0 Security (BCP 240) | January 2025 | Section 5 |
| FAPI 2.0 Security Profile, OpenID Foundation | Final, February 2025 | Risk class 4 |
| RFC 8705, OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens | 2020 | Sender-constrained tokens |
| RFC 9449, OAuth 2.0 Demonstrating Proof of Possession (DPoP) | 2023 | Sender-constrained tokens |
| RFC 9126, OAuth 2.0 Pushed Authorization Requests | 2021 | FAPI 2.0 |
| RFC 9457, Problem Details for HTTP APIs | 2023 | Error format |
| RFC 9745, The Deprecation HTTP Response Header Field; RFC 8594, The Sunset HTTP Header Field | 2025; 2019 | Deprecation signalling |
| OWASP API Security Top 10, owasp.org | 2023 edition | Design review |
| WCAG 2.2, W3C | Recommendation | Portal accessibility |
| [Vendor documentation] | [Version] | [Product limits and policy names] |
Standard and licence note
Based on public specifications: the OpenAPI Specification 3.2 (OpenAPI
Initiative, Apache License 2.0), IETF RFC 9700, RFC 8705, RFC 9449,
RFC 9126, RFC 9457, RFC 9745 and RFC 8594, and the FAPI 2.0 Security
Profile (OpenID Foundation). The OWASP API Security Top 10 is referenced
by name only; no OWASP text is reproduced. Gateway, portal and identity
product names are trademarks of their owners; this template is not
affiliated with or endorsed by them. This template is original text
written for this collection. Check the current official version of every
specification and the vendor documentation before use. Template
licence: MIT.