API security protects operations, data, and exposed resources from unauthorized access or harmful use. It limits what authorized consumers and end users can access while reducing privacy, financial, operational, and reputational harm. section 12.0 section 12.1
Treat security as a design constraint across capability identification, HTTP representations, data modeling, and OpenAPI documentation—not as a one-time implementation task. Revisit it whenever the API changes. section 12.2.1 section 12.2.2
Shopping API order retrieval
A website obtains an access token from an authorization server, then sends GET /orders with an Authorization header over HTTPS. The resource server validates the consumer, checks the order scope, identifies the end user from the token, and returns that user’s orders. section 12.1.1
Figure 12.1 The shopping website gets an access token to call the Shopping API to retrieve an end user’s orders. Based on the token, the Shopping API implementation verifies that the consumer has appropriate permissions before returning the user’s data.
Use the call-flow diagram to follow authentication, secure transport, scope validation, and end-user data selection. section 12.1.1
Design decisions that reduce API security risk include:
- Expose only necessary data and operations, and avoid revealing provider-side business logic or infrastructure details. section 1.2.3 section 12.2.2
- Define clearly who can see or do what; partition access with scopes based on operations, resources, use cases, read/write actions, consumers, or end users. section 12.11 section 12.2.2
- Protect integrity by conditioning updates on fresh data and preventing replay of element-creation requests. section 12.2.2 section 12.11
- Document security requirements, scopes, and errors in OpenAPI; return 401 for token problems, 403 for fixable permissions, and 404 for non-fixable access failures. section 12.11
- Review security-breaking changes deliberately: replacing API keys with mutual TLS may require a breaking change, while temporary coexistence can ease migration. section 15.3
Health and fitness data review
Before allowing every user to read every profile or workout, inspect fields such as phone numbers, email addresses, birth dates, and GPS coordinates. Decide which data and operations are necessary for the sharing use case and remove or restrict the rest. section 12.13
