15. API and Integration Security #
15.1 Authentication and authorization #
All external and internal APIs must enforce strong authentication and least‑privilege authorization. User‑facing flows must use OAuth 2.0 with OIDC (Authorization Code + PKCE). Service‑to‑service integrations must use OAuth 2.0 Client Credentials or mutual TLS (mTLS) with certificate pinning where feasible. Scopes/roles must be narrowly defined to the minimal set of actions and resources required. PENDING: Allowed grant types (confirm Auth Code+PKCE, Client Credentials, mTLS); scope naming conventions
15.2 Tokens and sessions #
Access tokens must be short‑lived; refresh tokens should be avoided unless strictly required by the flow. If refresh tokens are used, they must be rotation‑based and time‑limited. Tokens must be signed using a modern algorithm and validated for issuer, audience, expiry, and nonce where applicable. Tokens and session cookies must never be logged. PENDING: Access token TTL (__ minutes); refresh token policy (enabled/disabled; TTL __ days)
15.3 Input validation and schema enforcement #
All inputs—including headers, query parameters, body content, and file metadata—must be validated against strict schemas (e.g., JSON Schema) and sanitized. Reject requests with unexpected or malformed fields and enforce conservative request/response size limits. Output must be encoded appropriately to prevent injection in downstream consumers.
15.4 Rate limiting and abuse protection #
Apply rate limiting and throttling per API key/client and per IP/user to mitigate brute force, credential stuffing, and abuse. Enforce burst and sustained limits and block or tarp it offenders. Implement idempotency for unsafe methods where appropriate to prevent replay/duplicate processing. PENDING: Default per‑endpoint limits (e.g., login attempts/minute; request size cap __ MB)
15.5 Service‑to‑service security #
When APIs are consumed by backend services, prefer mTLS or Client Credentials with narrowly scoped permissions. Secrets for service‑to‑service calls must be vaulted and rotated regularly and upon personnel change. Avoid long‑lived static credentials; prefer short‑lived tokens and signed requests.
15.6 Secrets and keys #
API keys, client secrets, and signing/encryption keys must be stored only in an approved vault/KMS, injected at runtime, and rotated on a defined schedule. Keys must be unique per environment and application. Never hard‑code keys in source, images, or configuration files; never expose keys in URLs, error messages, or logs.
15.7 Error handling and security headers #
Return generic error messages that do not leak stack traces, internal identifiers, or configuration details. Include appropriate security headers for web/API responses (e.g., Content‑Security‑Policy for web content, Referrer‑Policy, X‑Content‑Type‑Options, and HSTS where applicable) to reduce client‑side risk. PENDING: Header baseline and any CSP defaults
15.8 API versioning and deprecation #
Version APIs explicitly (e.g., /v1) and communicate deprecations with reasonable notice periods. Deprecation windows must consider client update cycles and contractual obligations. Provide migration guidance and, where feasible, backward‑compatible changes.
15.9 Documentation and discovery #
Publish accurate, access‑controlled API documentation (e.g., OpenAPI/Swagger) that reflects authentication requirements, scopes, rate limits, input/output schemas, and error codes. Documentation must be updated with each release that changes behavior and included in the release evidence when materially altered.
15.10 Monitoring and logging #
Emit SIEM‑ready logs for authentication/authorization decisions, scope evaluations, permission/policy changes, request/response metadata (verb, route, caller identity, status, latency), and rate‑limit/abuse events. Log AV results for any upload endpoints. Include who/when/where/what/outcome and a correlation ID, with sensitive data redacted. PENDING: CLD SIEM forwarding requirement/method; minimum log fields confirmation
15.11 Testing #
Perform DAST focused on API endpoints before production release, including tests for auth bypass, IDOR, injection, mass assignment, rate‑limit evasion, and schema validation failures. Include API endpoints in annual third‑party penetration testing, with fixes verified for Critical/High findings. Contract tests must cover auth flows, scope enforcement, and error handling.
15.12 Third‑party and public APIs #
When consuming third‑party APIs, assess and document the security posture (auth model, scopes, rate limits, data residency, logging), and ensure contractual safeguards for incident notifications and changes. For any public‑facing CLD APIs, require key management with issuance/rotation controls, consumer registration, and abuse monitoring tied into alerting with on‑call targets. PENDING: On‑call acknowledgment targets (Sev1 ≤ __ minutes; Sev2 ≤ __ minutes)
15.13 Exceptions #
Any deviation from these requirements (e.g., temporary Basic Auth during migration) requires a documented exception detailing scope, rationale, compensating controls (e.g., IP allowlists, reduced token TTLs, enhanced monitoring), owner, ISO recommendation, Executive Sponsor approval, and expiry.