API security best practices

Why APIs need their own security thinking

A web page hides most of its logic on the server. An API exposes that logic directly, with predictable URLs, machine-readable responses and object IDs in every request. Attackers do not need to find a hidden form; they read your docs, change an ID and see what comes back. That is why the most common serious API flaws are authorization mistakes rather than exotic exploits. See API security for the short definition.

Authentication and authorization

Authentication answers "who is calling?" Authorization answers "may this caller do this to this object?" Both must run on every request, on the server, and they fail in different ways.

• Authenticate every non-public endpoint, including internal and admin ones. "Nobody knows this URL" is not a control.
• Authorize at the object level. Loading /invoices/inv_123 must check that the caller owns or may access inv_123, not just that they are logged in. Centralise this check so new endpoints cannot forget it.
• Authorize at the property level. Filter which fields a caller may read and which they may write, so a user cannot set role: "admin" by adding it to a request body.
• Authorize at the function level. Admin operations need explicit role checks, not just a different URL prefix.
• Deny by default. A new endpoint should be unreachable until someone grants access.

OAuth 2.0, API keys and tokens

OAuth 2.0 is the standard framework for delegated authorization: a user grants an application limited access to their data without sharing a password. Current guidance, collected in the OAuth 2.0 Security Best Current Practice (RFC 9700), recommends the authorization code flow with PKCE for user-facing apps, the client credentials flow for machine-to-machine calls, and no longer recommends the implicit or password grants.

API keys identify a calling application. They are simple and fine for server-to-server use, but they are long-lived secrets, so:

• Send them only in headers, never in URLs, where they leak into logs, browser history and referrers.
• Store only a hash on the server, show the full key once, and support rotation and multiple active keys.
• Scope keys to the minimum permissions and environments (test vs live) they need.
• Never embed secret keys in mobile apps or browser code; anything shipped to a client is public.

Access tokens are often JWTs. Validate the signature with an expected algorithm (never accept none), and check the issuer, audience and expiry on every request. Keep access tokens short-lived and use refresh tokens for longer sessions. For browser clients, configure CORS to allow only the origins you trust; CORS controls which web pages may read responses, and it is not a substitute for authentication.

Rate limits and input validation

Rate limiting protects availability and slows brute force and scraping. Apply limits per key, per user and per IP, with tighter limits on expensive or sensitive operations such as login, password reset and search. Return 429 Too Many Requests with a Retry-After header so well-behaved clients back off. Also cap request body size, page size, query complexity (for GraphQL) and upload size.

Validate every input against a schema: type, format, length, range and allowed values. Reject unknown fields rather than silently accepting them, which also closes off mass-assignment bugs. Use parameterised queries, encode output for its destination, and treat data from third-party APIs with the same suspicion as user input. A JSON Schema or OpenAPI document can drive this validation at the edge, often in an API gateway.

The OWASP API Security Top 10 (2023)

The OWASP API Security Top 10 is the most widely used list of API-specific risks. The 2023 edition:

1. API1: Broken Object Level Authorization. Accessing other users' objects by changing an ID.
2. API2: Broken Authentication. Weak or flawed login, token and credential handling.
3. API3: Broken Object Property Level Authorization. Reading or writing fields the caller should not, combining excessive data exposure and mass assignment.
4. API4: Unrestricted Resource Consumption. Missing limits on requests, payload sizes or costly operations.
5. API5: Broken Function Level Authorization. Regular users reaching admin functions.
6. API6: Unrestricted Access to Sensitive Business Flows. Automated abuse of flows such as purchasing, sign-up or posting.
7. API7: Server Side Request Forgery. The API fetching an attacker-supplied URL.
8. API8: Security Misconfiguration. Verbose errors, missing hardening, permissive CORS, unpatched components.
9. API9: Improper Inventory Management. Forgotten old versions, undocumented endpoints and stale environments.
10. API10: Unsafe Consumption of APIs. Trusting data from third-party APIs too much.

Notice that three of the ten are authorization failures. Notice too that API9 is a lifecycle problem: old versions that were never retired keep old vulnerabilities alive. A real deprecation process and an accurate inventory are security controls.

Logging, monitoring and response

• Log every authentication event, authorization failure, rate-limit hit and validation rejection, with a request ID, caller identity and timestamp.
• Never log secrets, full tokens, passwords or unnecessary personal data. Redact at the source.
• Alert on patterns, not single events: one account walking through sequential IDs, a spike in 401 or 403 responses, traffic to a deprecated version.
• Keep an inventory of every API, version and environment, and who owns it. API monitoring should cover all of them, not only the current version.
• Have a plan to revoke keys and tokens quickly, and rehearse it.

Security during change

Many security regressions arrive inside ordinary changes: a refactor drops an authorization check, a new field exposes internal data, a migration leaves the old version running. Add authorization tests to your API testing strategy, diff specs for newly exposed fields, and when you replay recorded traffic against a new version, redact sensitive data and run only in isolated environments. Teams using a tool such as Releo to verify migrations with traffic replay should apply the same rules to captured requests.

Frequently asked questions

Related guides

• API testing: types, tools and a strategy that works
• API design best practices
• How to deprecate an API