API Security
Context
Microservices, mobile apps, SaaS integrations, partners and IoT devices all talk through APIs, so for most organisations the API layer is the largest exposed surface. A web application firewall built for rendered pages sees only part of it. APIs expose data and business logic directly, and most serious attacks go after authentication, object-level authorisation, data exposure, rate limits and abuse of business functions.
Summary
Every call passes four layers. The API gateway authenticates the caller, applies rate limits and checks the request against its schema. The authorisation layer decides whether this caller may act on this object. The validation layer checks every input before business logic sees it. The monitoring layer looks for credential abuse, unusual usage and data leaving in bulk. Around the call sits the lifecycle: schema-first design, testing in the pipeline, an inventory of published APIs, and retirement of old versions.
The pattern covers the whole lifecycle and applies to REST, GraphQL, gRPC, WebSocket and event-driven APIs. The ArchiMate view covers less: one inbound call from a consumer outside the organisation to a service inside it. The 32 controls on that path are the architecture; the other 15 come from the organisation around it.
Key principles
Validate at three points. Input is checked at the web application firewall, at the gateway and in the service (SI-10 three times). Teams often build one and stop. Only the service-side check knows the business rules.
The identity provider is a rate limiter too. The DDoS service absorbs floods of traffic (SC-05, SC-06) and the gateway applies per-client rate limits (SC-07). The identity provider throttles authentication: it slows down and then locks out repeated failed attempts (AC-07), which stops credential stuffing and password spraying before any token is issued. Short token lifetimes and session termination (AC-12) limit how long a token that does get through stays useful.
The API inventory is a security control. An API missing from the inventory (CM-08) is not behind the gateway, not tested and not monitored. The same inventory tells you which third-party APIs you depend on when a supplier is compromised.
This pattern is available in two notations, and each takes a slightly different angle. The overview gives you a helicopter view of how API security fits into your organisation as a security capability. The ArchiMate view shows the same pattern in ArchiMate notation, and splits it into a threat view, which says what can go wrong, and a control view, which says what we are doing about it. That view should be useful to security architects who work where ArchiMate is the common notation, or to anyone who wants more detail on this pattern.
Click any control badge to view its details. Download SVG
The overview diagram reads top to bottom in six bands.
- Governance, standards and training.
- API consumers: web clients, mobile apps, partners and services.
- The API security stack: the API gateway, the authorisation layer, validation and protection, and service-to-service mTLS.
- Backend services and data.
- API lifecycle management.
- API monitoring and incident response.
Control identifiers appear as badges beside the block that applies them, and each badge links to that control's page. The legend explains the trust boundary marks. The footer carries the pattern ID and name, the control count, the authors, the status, the date and the standards the pattern addresses.
The view opens showing the whole diagram, so the labels start small. Zoom in to read them, and click any box for its detail.
How to read this
Drag the diagram, or use the arrow keys, to move around. Plus and minus zoom. 0 shows the whole view again. Escape clears the selection and moves to the text below.
For a control the panel carries the link to its page; ctrl-click, or cmd-click, the box to open that page straight away.
This view shows one API interaction: a consumer outside the organisation calling a service inside it. It draws the components that take part, the threats that apply at each step, and the controls those threats need. The scope is the inbound call only.
Read the interaction from top to bottom. NORA-1: External holds the API consumer, with a web client, a mobile app and a server-based application inside it. NORA-4: Back Office holds the service and the data store. The call runs from External down to Back Office.
Threats sit in a column beside the zones, each at the height of the step it applies to. Controls follow in the next column, one box each. A control that answers two threats can be drawn twice, once beside each; CM-08 is the only one. A narrow column beside the controls holds the four refinements of SI-10: Allowlisting, Blocklisting, Detailed validation and Data sanitization. The view opens with the controls hidden. Tick Controls to show them, and the view becomes a map from each threat to the controls that answer it.
An arrowhead means the control mitigates the threat it points at, and every mitigation relation has one. A relation running left from a threat to a component means the threat applies there. Every threat also carries a STRIDE-LM category. The view does not draw it. The detail panel beside the diagram shows it when you select a threat.
For every control the threats require, this view shows the security service that delivers it.
The three network zones run down the middle. NORA-1: External holds the API consumer and its three client types. NORA-2: DMZ holds STS-21 distributed denial of service protection, STS-17 web application firewall and STS-23 secure service gateway. NORA-4: Back Office holds the service, the data store and eight more security services. The controls sit left and right of the zones, each beside the service that delivers it. A control appears once for each service that delivers it. The view draws SI-10 three times: at the web application firewall, at the gateway and at the service.
Key Control Areas
The third column names the security service that delivers each area in the ArchiMate view. Controls marked organisation level are part of the pattern but sit outside the inbound call.
| Area | Controls | Delivered in the ArchiMate view by |
|---|---|---|
| API Authentication and Identity Management Every call is authenticated, with OAuth 2.0 tokens, signed API keys or mutual TLS, never basic authentication over plain HTTP. IA-02 covers the organisation's own users and IA-08 external ones: partners, third-party developers and public consumers. IA-04 runs the lifecycle of client IDs and API keys, from issue to revocation. IA-05 sets how authenticators are handled: signing keys rotated, keys long enough, secrets kept in a secrets manager rather than in code or config. IA-09 authenticates services to each other with mutual TLS, workload identity (SPIFFE) or signed tokens, instead of trusting the network. In practice: access tokens of about 15 minutes, rotating refresh tokens, and key rotation that does not need downtime. | IA-02, IA-04, IA-05, IA-08, IA-09 |
|
| API Authorisation and Access Control Authorisation is checked per endpoint, per object, per field and per operation. AC-03 enforces it from scopes, roles or attributes, and the check that matters most is per object: may this caller read this record, not just this endpoint (OWASP API1). AC-04 stops data crossing trust boundaries or reaching a caller who should not see it. AC-06 keeps token scopes to what the operation needs. AC-07 locks out repeated failed logins, which stops credential stuffing. AC-10 limits concurrent sessions per identity. AC-12 ends sessions: short-lived access tokens, refresh tokens that rotate, and revocation that reaches every enforcement point within seconds. | AC-03, AC-04, AC-06, AC-07, AC-10, AC-12 |
|
| API Gateway and Boundary Protection All traffic passes the gateway; no consumer talks to a backend service directly. SC-07 makes the gateway the boundary: it terminates TLS, validates tokens, applies rate limits, checks the schema and forwards only requests that pass. AC-17 covers remote and administrative access to the API platform itself. AC-20 governs the external APIs the organisation calls: each is listed, risk-assessed and watched for outages, incidents and breaking changes. AC-21 ties what an endpoint returns to data classification: public endpoints return public data, partner endpoints stay within the contract, internal endpoints serve authenticated internal services. | SC-07, AC-20 organisation level: AC-17, AC-21 |
|
| Input Validation and Injection Prevention SI-10 validates every input (path, query, headers and body) against the API schema before business logic runs, using allow-lists rather than block-lists. That stops SQL, NoSQL and command injection, XML external entities and server-side request forgery. SI-03 scans uploads and catches encoded or disguised payloads. SI-11 returns standard error codes without stack traces, schema details or internal paths. SI-15 filters output so a response carries only the fields the consumer needs (OWASP API3). | SI-10, SI-03, SI-11 organisation level: SI-15 |
|
| Transport Security and Cryptography SC-08 requires TLS 1.2 or later on every API call, internal ones included, with no fallback to HTTP; in a service mesh, mutual TLS adds service identity. SC-13 sets the cryptography: asymmetric token signing (RS256 or ES256, not a shared HS256 secret), API keys of at least 256 bits, and JWE where the payload itself is sensitive. SC-23 binds tokens to the client and checks signature, expiry and audience on every request. SC-28 protects data at rest: encrypted logs that hold request bodies, API keys stored as hashes, encrypted caches and queues. | SC-08, SC-13, SC-23 organisation level: SC-28 |
|
| API Inventory and Lifecycle Management CM-08 keeps an inventory of every API: endpoint, version, owner, consumers, authentication method, data classification and status. Undocumented APIs and old versions still running are what it is there to find. CM-02 sets the baseline for every deployment: gateway policies, security headers (CORS, HSTS), TLS versions and default rate limits. CM-03 controls change: schema changes are versioned and contract-tested in CI/CD, and breaking changes come with notice and a migration period. CM-07 removes what is not needed: unused HTTP methods, debug endpoints, GraphQL introspection in production, and retired versions on a published date. | CM-02, CM-03, CM-07, CM-08 |
|
| API Monitoring and Anomaly Detection Monitoring covers security events and abuse of business functions. AU-02 lists what is logged: authentication attempts, authorisation decisions, rate-limit hits, validation failures and access to sensitive data. AU-03 sets the record: time, source, identity, endpoint, method, status, size and a correlation ID. AU-12 logs at the gateway and in each service so a request can be traced end to end. AU-06 reviews the records for credential stuffing, sequential ID enumeration, bulk scraping through pagination and unusual transactions. SI-04 watches traffic as it happens for jumps in volume, new locations or clients, and responses larger than usual. CA-07 tracks the security state of the API estate over time. | AU-02, CA-07, SI-04 organisation level: AU-03, AU-06, AU-12 |
|
| API Security Testing and Assessment RA-03 threat-models each API at design time: trust boundaries, data flows, authentication points and abuse cases. SA-08 builds the answers into the design: security constraints in the schema, authorisation that fails closed, validation at gateway and service. SA-11 has developers test it: unit tests for authorisation logic, contract tests for the schema, integration tests across the stack. RA-05 scans deployed APIs in the pipeline for injection, authentication bypass and data exposure. CA-02 adds periodic assessment: penetration tests against the OWASP API Top 10, fuzzing, and attempts to bypass authorisation. | RA-05, SA-11 organisation level: CA-02, RA-03, SA-08 |
|
| Other controls In the pattern, but in none of the eight areas. | SC-05, SC-06, SR-02, SR-03 |
|
Every control on the inbound path answers one of the threats in the ArchiMate view. Organisation-level controls are part of the pattern but sit outside the inbound call: governance, training, incident response, at-rest protection and assessment.
When to Use
Use this pattern wherever the organisation publishes or consumes APIs. It matters most for public APIs used by third-party developers, mobile apps on REST or GraphQL, microservices with heavy service-to-service traffic, open banking and PSD2, partner integrations, and IoT fleets.
When NOT to Use
It is overhead for an internal monolith that exposes no APIs, and of little use where integration is file-based only (SFTP, batch). A prototype can defer most of it, but not authentication and input validation.
Typical Challenges
Legacy APIs are hard to retrofit: basic authentication, no input validation, responses that return too much. Teams publish APIs outside governance, and nobody knows they exist. Deeply nested GraphQL queries take a service down unless depth and cost are limited. Rate limits are hard to set: too coarse blocks heavy legitimate users, too fine is costly to run. API keys spread across consumers make rotation and revocation painful without central key management. East-west traffic between microservices is expensive to monitor in full. When the specification drifts from the implementation, tests pass against an API that no longer exists. Partner contracts limit which controls can be imposed. Old versions stay alive because consumers do not migrate.
Three of these challenges appear in the ArchiMate view. Input validation is drawn three times: at the web application firewall, at the gateway and at the service. Teams build one of the three and stop. Rate limiting is not only a network control, because AC-10 and AC-12 sit with the identity provider, and that pair stops a flood of valid sessions. CM-08 answers shadow APIs, and supply chain compromise depends on it too, so an out-of-date inventory of published APIs leaves both threats unanswered.
Threat Resistance
The pattern answers the OWASP API Security Top 10 (2023) and four threats outside it: injection, interception, supply chain compromise and platform vulnerabilities. Object-level authorisation is checked in the service, not only at the gateway (AC-03, AC-06). Tokens are short-lived, bound to the client and revocable (IA-05, SC-23, AC-12). Input is validated against the schema at three points (SI-10), and output is filtered to the fields the consumer needs (SI-15). Rate limits work at the network and at the identity provider (SC-05, AC-10). The table below gives each threat, how it is classified and which controls counter it. Open a threat for its scenario.
| Threat | OWASP API | Threat in the model | STRIDE-LM | Controls |
|---|---|---|---|---|
Broken authentication and credential stuffing ScenarioAn attacker replays leaked username and password pairs, or guesses API keys, against the login or token endpoint until one works. APIs make this easy: they answer success and failure in machine-readable form and rarely show a CAPTCHA. The attack lands at the identity provider before any business logic runs. | API2 | CAPEC-115: Authentication Bypass | Spoofing | AC-07, IA-02, IA-04, IA-05, IA-08, SI-04 |
Broken object level authorization (BOLA/IDOR) ScenarioAn authenticated caller changes an object ID in the request, say /accounts/1043 to /accounts/1044, and gets another customer's record. The token is valid, so the gateway passes the call; only the service knows who owns the object. It is the most common serious API flaw (OWASP API1). | API1 | Unauthorized changes or manipulation of data records | Tampering | AC-03, AC-04, AC-06, SI-04 |
Injection attacks via API parameters ScenarioA caller puts SQL, NoSQL, shell or template syntax into a parameter, header or JSON field, and the service hands it to an interpreter. Schema validation at the gateway catches wrong types, not a well-formed string carrying a payload, so the service has to validate as well. | — | CAPEC-242: Code Injection | Tampering | AC-04, SC-07, SI-03, SI-04, SI-10, SI-11 |
Excessive data exposure in API responses ScenarioThe service returns whole database objects and relies on the client to show only some fields. Anyone reading the raw response sees internal IDs, other users' personal data or security attributes. The caller may see the object, just not every field of it, which is what separates this from object-level authorisation failure. | API3 | CAPEC-116: Excavation | Information disclosure | AC-03, AC-04, AC-06, SI-04 |
Rate limiting bypass and API abuse ScenarioA caller gets round per-key or per-IP limits by rotating keys, spreading requests over many addresses or opening many valid sessions, then scrapes data or abuses a function such as a voucher or price check. Each request is legitimate; the abuse is in the volume and the pattern. | API4 | CAPEC-125: Flooding | Denial of service | AC-10, AC-12, AU-02, SC-05, SC-06 |
Mass assignment and parameter tampering ScenarioThe service binds the request body straight onto an internal object, so a caller who adds a field such as isAdmin or price changes something the API never meant to expose. The caller acts on their own object, but on fields they should not be able to write. | API3 | Unauthorized changes or manipulation of data records | Tampering | AC-03, AC-04, AC-06, SI-04 |
Server-side request forgery via API input ScenarioAn API that fetches a URL supplied by the caller, to import an image or call a webhook, is pointed at an internal address such as a cloud metadata endpoint or an admin console. The request leaves from inside the network, so perimeter controls never see it. The ArchiMate view does not name this threat yet. | API7 | not covered | — | — |
Third-party API supply chain compromise ScenarioA third-party API the organisation calls, or a library used to build the API, is compromised and starts returning malicious data or leaking what it is sent. The organisation's own controls still work; it is the trust placed in the supplier that fails. | API10 | API supply chain compromise | Tampering | AC-20, CM-08, IA-09, SA-11, SI-04, SR-02, SR-03 |
Man-in-the-middle on API traffic ScenarioSomeone on the network path, on public Wi-Fi, in a compromised proxy or between internal services, reads or changes API traffic, bearer tokens included. Without TLS a stolen token is as good as a password; without mutual authentication one service cannot tell another from an impostor. | — | CAPEC-94: Adversary in the Middle (AiTM) | Tampering | SC-08, SC-13, SC-23 |
Shadow API and zombie API exposure ScenarioTeams publish APIs outside the gateway, or old versions keep running after the new one ships. Nobody tests, monitors or patches them, and attackers find them by enumerating hostnames, paths and version numbers. | API9 | CAPEC-169: Footprinting | Information disclosure | CA-07, CM-02, CM-03, CM-08 |
Token theft and replay attacks ScenarioAn attacker takes an access or refresh token from browser storage, a log, a mobile app or a network trace, and replays it as the user until it expires. The token is genuine, so authentication succeeds. | API2 | CAPEC-21: Exploitation of Trusted Identifiers | Spoofing | AC-12, IA-05, SC-23, SI-04 |
API denial of service via resource exhaustion ScenarioA caller sends requests that are cheap to send and expensive to answer: deeply nested GraphQL queries, huge page sizes, large uploads. The service or its database runs out of CPU, memory or connections. Unlike rate-limit abuse, a handful of requests can be enough. | API4 | CAPEC-125: Flooding | Denial of service | AC-10, AC-12, AU-02, SC-05, SC-06 |
Not named by OSA ScenarioAn attacker exploits a known flaw in the platform under the API: the gateway product, the container runtime, the operating system or firmware. Application controls do not help once the layer beneath them is taken. This threat comes from the Cyber Security Coalition's model. | — | Exploit hardware or platform vulnerabilities | Elevation of privilege | CM-07, RA-05, SI-04 |
The ArchiMate view does not answer one of OSA's threats: server-side request forgery. It is answered by SI-10 and SC-07, already in the pattern, but no threat in the model names it.
The OWASP column uses the 2023 edition of the OWASP API Security Top 10. Injection and adversary in the middle have no entry there, so they show a dash. API3 merges the 2019 entries for excessive data exposure and mass assignment, so two rows carry it.
Two model threats answer two OSA threats each: CAPEC-125: Flooding and Unauthorized changes or manipulation of data records. They should be split in a later version of the model.
Assumptions
The organisation builds or consumes APIs. An API gateway or reverse proxy exists or can be deployed. Teams design APIs schema-first (OpenAPI, GraphQL SDL, protobuf). OAuth 2.0 or a similar token service is available. Every consumer can be identified, including on public APIs, where an API key is the minimum for rate limiting and abuse tracking. A CI/CD pipeline runs automated tests. Logging can take the full API traffic volume.
The ArchiMate view adds two assumptions. The organisation enforces a network zoning model, and the view places every element in External, DMZ or Back Office. The consumer holds a valid access token before the first call reaches the web application firewall. An identity provider validates that token and issues the internal token used behind the gateway. Issuing the first token is outside this pattern.
Known Uses
- Single-page web application calling an API. The browser holds the token, so session handling carries most of the risk.
- Business-to-business API integration. The caller is a server, so IA-09 authenticates the calling service.
- Open banking. The consumer is a third party, so AC-20 and the supply chain controls apply.
Variants, Refinements and Combinations
The model records one variant, API IA Threat Model, covering identity and authentication in more detail. No others are known.
Developing Areas
- GraphQL security tooling lags behind REST. WAF rules, gateway policies and scanners were built for REST; GraphQL adds nested queries, alias batching and field-suggestion enumeration that generic tools miss. Field-level authorisation and cost-based rate limiting still need custom work.
- Business-logic abuse such as coupon stacking, inventory hoarding and price scraping looks like legitimate use at the protocol level. Catching it needs behavioural baselines and business context, which gateway and WAF products are only starting to provide.
- Machine-to-machine credentials do not scale by hand. With hundreds of services, each needing its own keys, certificates and tokens, manual rotation breaks down. Workload identity (SPIFFE/SPIRE) and identity federation solve it, at a real infrastructure cost.
- Automated API discovery from traffic, code repositories and cloud configuration can find undocumented and forgotten APIs, but its accuracy varies, and keeping the inventory current is still mostly manual.
- Runtime protection inside or beside the service sees what the gateway cannot: object-level authorisation failures and data exposure that depend on the application's data model. The cost is added latency on high-volume APIs.
Related Patterns
Patterns that operate within or alongside this one. Click any to view.
On the inbound call path (32)
Each answers a threat in the ArchiMate view.
Organisation level (15)
Governance, training, incident response, at-rest protection and assessment, outside the inbound call.
References
- OWASP API Security Top 10 (2023)
The standard list of API risks, including broken object-level authorisation, broken authentication and unrestricted resource consumption.
- NIST SP 800-204: Security Strategies for Microservices-based Application Systems
NIST guidance for microservices: API gateways, service mesh and service-to-service authentication.
- NIST SP 800-204A: Building Secure Microservices-based Applications Using Service-Mesh Architecture
Service mesh in detail: mutual TLS, service identity and traffic monitoring.
- NIST SP 800-53 Rev 5: Security and Privacy Controls
The control catalogue this pattern maps to.
- RFC 6749: The OAuth 2.0 Authorization Framework
The OAuth 2.0 specification. Read with RFC 7636 (PKCE), RFC 7519 (JWT) and RFC 8725 (JWT best current practice).
- OpenAPI Specification 3.1
The usual format for describing REST APIs; a schema in it drives validation, tests and documentation.
- OWASP Web Security Testing Guide: API Testing
How to test APIs: reconnaissance, object- and function-level authorisation, data exposure and GraphQL.
- Google API Design Guide
Google's API design rules, including authentication, errors and versioning.
- Security Patterns: API Services Security Pattern
Cited by the Cyber Security Coalition pattern document behind the ArchiMate view.
- OWASP API Security Project
Project page for the OWASP API Security Top 10; the threat table maps to its 2023 edition.
- OWASP Cheat Sheet: Network Segmentation
Background for the External, DMZ and Back Office zoning the ArchiMate view assumes.
- OWASP Cheat Sheet: OAuth 2.0
Token handling behind the identity provider and internal token in the ArchiMate view.
Attribution
ArchiMate view contributed by the Cyber Security Coalition, Enterprise Security Architecture focus group (Michael Boeynaems, Fabien Antiga, Roos Hubrechtsen, Kris Vercauteren), under CC BY-SA 4.0. Release 26.02, before the ArchiMate view, is kept in the pattern archive.
Standards and catalogues used in the model
- NIST SP 800-53 Rev 5, for the control identifiers and titles. Base controls only.
- MITRE CAPEC, meta attack patterns, for the threat names.
- STRIDE-LM, for the threat categories.