API Security Best Practices 2026: The Discovery-Definition-Protection Framework

Why APIs Are the #1 Attack Surface in 2026

The numbers tell a clear story: API traffic represents 83% of total internet traffic in 2026 (up from 71% in 2023), driven by the proliferation of single-page applications, mobile apps, microservices, and third-party integrations. Every API call is a potential attack vector that bypasses traditional UI-layer controls.

API-specific attacks have increased 681% since 2021. The drivers:

• APIs are designed for machine consumption — they're discoverable, predictable, and lack the friction of human-facing UIs
• Microservices sprawl — organizations running hundreds of microservices accumulate thousands of internal and external API endpoints
• Mobile apps expose APIs — any API consumed by a mobile app is accessible to anyone who reverses the app or intercepts its traffic
• Third-party integrations — SaaS integrations, webhooks, and partner APIs create external API surfaces that security teams often don't control
• AI-assisted API enumeration — attackers use AI tools to intelligently guess undocumented API endpoints based on naming patterns

Shadow APIs: The Unknown Attack Surface

A shadow API is any API endpoint that accepts traffic but isn't in the organization's official API inventory or documentation. They accumulate through predictable organizational dynamics:

How Shadow APIs Form

Deprecated endpoints: An API endpoint is "retired" in documentation but never actually removed from the codebase. Internal clients still call it; attackers discover it through enumeration. These deprecated endpoints often don't receive security updates and may be running older, vulnerable code paths.

Microservices sprawl: In large organizations, individual teams create APIs for inter-service communication. These APIs may never be inventoried centrally, lack authentication entirely (relying on network isolation that no longer exists), and expose sensitive data assuming they're "internal only."

Development and staging bleed: Test APIs created for development are accidentally deployed to production. They often lack authentication, rate limiting, or input validation — they were never intended to be public.

Third-party acquisition: When organizations acquire companies or integrate SaaS products, the acquired systems' APIs become part of the attack surface without proper security review.

The danger of shadow APIs: they're often called the "left side of the kill chain" — attackers discover them before defenders do.

Phase 1: Discovery — Find Every API You Have

You cannot protect what you don't know exists. API discovery is the foundation of a security program and often produces surprising results — organizations routinely find 20-40% more APIs than they had documented.

Traffic-Based Discovery

The most comprehensive discovery method is passive traffic analysis: mirror all HTTP/HTTPS traffic through an API discovery sensor that parses request paths, methods, parameters, and response schemas. This discovers:

• Every endpoint receiving real traffic (including shadow APIs)
• The actual parameters and data types being sent (vs. what documentation claims)
• Endpoints receiving unusual traffic patterns (potential existing exploitation)
• Authentication patterns actually in use across different endpoints

Spec-Diff Analysis

Compare discovered endpoints against your existing OpenAPI/Swagger specification. The diff reveals:

• Undocumented endpoints — in traffic but not in spec (shadow APIs)
• Spec-only endpoints — documented but never called (dead code that can be removed)
• Parameter drift — endpoints accepting parameters not in the spec (potential injection vectors)
• Response schema drift — APIs returning data not described in spec (potential excessive data exposure)

Active Crawling

Supplement passive discovery with authenticated crawling: send requests to every URL pattern in your specification, plus intelligent guesses for common patterns (/v2/, /api/internal/, /admin/, /debug/). Authenticated crawling as different user roles reveals authorization boundary failures.

Phase 2: Definition — Create a Security Schema

Once you know what APIs exist, define exactly what "good" looks like for each endpoint. This is your API security schema — a positive security model that describes all allowed traffic and implicitly blocks everything else.

OpenAPI/Swagger as Security Contract

OpenAPI 3.x specifications serve dual purposes: developer documentation and security contract. A security-grade OpenAPI spec defines:

• Allowed HTTP methods per endpoint (GET, POST, PUT, PATCH, DELETE)
• Required vs optional parameters
• Parameter types (string, integer, boolean) and formats (date, email, uuid)
• Value constraints (minimum/maximum for numbers, minLength/maxLength for strings, regex patterns)
• Required authentication schemes per endpoint
• Allowed response codes

openapi: 3.0.3
paths:
  /api/v1/users/{userId}/orders:
    get:
      summary: Get user orders
      security:
        - BearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, processing, shipped, delivered, cancelled]
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Order list
        '401':
          description: Unauthorized
        '403':
          description: Forbidden — userId does not match authenticated user

Behavioral Baseline

Beyond static schema, capture a behavioral baseline for each endpoint:

• Normal request rate (requests per minute, per hour, per day)
• Geographic distribution of legitimate callers
• Typical response times and sizes
• Authentication method distribution

Phase 3: Protection — Enforce at the Edge

With a complete API inventory and security schema, enforcement becomes systematic. Zlycloud's API Shield enforces the schema at the CDN edge — requests that don't conform never reach your origin servers.

Schema Validation

Every incoming request is validated against the OpenAPI specification:

• Reject requests to endpoints not in the specification (blocks shadow API probing)
• Reject wrong HTTP methods (DELETE on a read-only endpoint)
• Reject parameters of wrong types (string where integer expected — common injection staging)
• Reject values outside allowed ranges (negative quantity, UUID with invalid format)
• Reject missing required authentication

Schema validation blocks a significant class of injection attacks before any application code runs: a SQL injection payload in an integer field is rejected at the type-validation layer.

Anomaly Detection

Statistical analysis against the behavioral baseline identifies:

• Request rates exceeding normal by 3σ or more (potential enumeration or DoS)
• Unusual geographic access patterns (credentials used from unexpected locations)
• Sequential resource ID enumeration (BOLA/IDOR attack patterns)
• High error rate from a single source (authentication brute force, scanner activity)

OWASP API Security Top 10: Brief Overview

The OWASP API Security project maintains its own Top 10, distinct from the web application Top 10. The 2023/2026 edition covers:

1. BOLA (Broken Object Level Authorization) — Accessing other users' resources via ID manipulation
2. Broken Authentication — Weak token generation, missing token expiry
3. Broken Object Property Level Authorization — Mass assignment, excessive data exposure
4. Unrestricted Resource Consumption — No rate limiting, missing pagination limits
5. Broken Function Level Authorization — Accessing admin functions as regular user
6. Unrestricted Access to Sensitive Business Flows — Automated abuse of legitimate workflows
7. Server-Side Request Forgery (SSRF) — APIs that fetch URLs provided by users
8. Security Misconfiguration — CORS wildcards, verbose errors, missing TLS
9. Improper Inventory Management — Shadow APIs, unretired endpoints
10. Unsafe Consumption of APIs — Trusting third-party API responses without validation

For the broader web application vulnerability context, see our OWASP Top 10 2026 article which covers injection, access control, and cryptographic failures in depth.

Authentication Methods: JWT vs OAuth 2.0 vs API Keys

Rate Limiting Strategies: Fixed Window vs Sliding Window vs Token Bucket

Fixed Window

The simplest approach: allow N requests per time window (e.g., 100 requests per minute). Reset the counter at the start of each window. The vulnerability: an attacker can send 100 requests in the last second of one window and 100 in the first second of the next window — 200 requests in 2 seconds while staying within the "100 per minute" limit.

# Fixed window: simple but exploitable at window boundaries
Window 1 (0:00-1:00): allow 100 requests
Window 2 (1:00-2:00): allow 100 requests
# Attack: 100 req @ 0:59, 100 req @ 1:01 = 200 req in 2 seconds ✓

Sliding Window

Count requests in a rolling time window rather than fixed intervals. At any point in time, the rate is calculated over the previous N seconds. More accurate but requires storing per-request timestamps — higher memory cost at scale.

Token Bucket

The most flexible algorithm for API rate limiting. Each API consumer has a "bucket" that fills at a constant rate (e.g., 10 tokens per second) up to a maximum capacity (e.g., 100 tokens). Each request consumes one token. If the bucket is empty, the request is rejected or queued. Token bucket naturally handles burst traffic — a client can accumulate tokens during quiet periods and spend them in a burst.

// Token bucket parameters for a production API
const bucket = {
  capacity: 100,          // max burst size
  refillRate: 10,         // tokens added per second
  currentTokens: 100,     // starts full
  lastRefillTime: now()
};

function allowRequest(bucket) {
  // Refill tokens based on elapsed time
  const elapsed = now() - bucket.lastRefillTime;
  bucket.currentTokens = Math.min(
    bucket.capacity,
    bucket.currentTokens + elapsed * bucket.refillRate
  );
  bucket.lastRefillTime = now();

  if (bucket.currentTokens >= 1) {
    bucket.currentTokens -= 1;
    return true;  // allow request
  }
  return false;  // reject: 429 Too Many Requests
}

Secure API Request: Complete Example

A properly secured API request demonstrates defense-in-depth authentication: the client presents a short-lived JWT access token in the Authorization header, an API key for service identification, and all sensitive data travels over TLS:

POST /api/v1/payments/initiate HTTP/2
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-API-Key: sk_live_4xKj8mNq2RvYpT9wZbLs
Content-Type: application/json
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
X-Idempotency-Key: pay_7f3a1b2c-9d4e-4f5a-8b6c-1a2b3c4d5e6f

{
  "amount": 9900,
  "currency": "USD",
  "recipient_account_id": "acct_1234",
  "description": "Order #98765"
}

# Response includes rate limit headers
HTTP/2 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709510460
Retry-After: (only present on 429)

# JWT payload (decoded) — short-lived, scoped, audience-restricted
{
  "sub": "user_abc123",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "exp": 1709510160,   // 15 minutes from issue
  "iat": 1709509260,
  "scope": "payments:write users:read",
  "jti": "unique-token-id"  // for replay prevention
}

Key security properties in this example:

• JWT uses RS256 (asymmetric signing) — the API can verify without access to the signing key
• 15-minute token expiry limits the blast radius of token theft
• Audience (aud) claim prevents token reuse across services
• Idempotency key prevents duplicate payment processing
• Rate limit headers inform clients of their consumption

For teams dealing with bot-driven API abuse — credential stuffing against authentication endpoints, automated enumeration of resource IDs — see our guide to ML-powered bot detection which covers how to distinguish legitimate API clients from automated abuse tools.