Cloudflare API Shield implementation guide
Use this guide to plan API Shield workstreams from API inventory through schema validation, mTLS, abuse controls, logging, and ongoing tuning.
Use this guide to plan API Shield workstreams from API inventory through schema validation, mTLS, abuse controls, logging, and ongoing tuning.
Topics: cloudflare, resource, cloudflare, shield, implementation, guide
Machine-readable context: /ai-index.json
Step by step
Implementation steps
- 1
Run API Discovery to enumerate the API endpoints Cloudflare actually sees, then reconcile that list against documented endpoints to surface shadow and undocumented APIs.
- 2
Label endpoints in Endpoint Management and classify them by sensitivity, authentication method, expected client type, and request volume so controls can be scoped per endpoint.
- 3
Upload or generate OpenAPI schemas and turn on Schema Validation in log mode first, reviewing non-conforming requests before any request is rejected.
- 4
Implement client authentication: configure mTLS with a Cloudflare-managed or uploaded CA for machine-to-machine and partner traffic, and enable JWT Validation for token-bearing endpoints.
- 5
Layer abuse controls: set per-endpoint Rate Limiting based on observed volume, align Bot Management signals with API traffic, and enable Sequence Mitigation where call order matters (for example, payment must follow cart).
- 6
Promote enforcement gradually — move Schema Validation, JWT Validation, and mTLS from log to block per endpoint as evidence accumulates, starting with the lowest-risk endpoints.
- 7
Wire visibility before and during enforcement: API Shield analytics, Logpush of HTTP and API events to the SIEM, and alerting on schema rejections, auth failures, and rate-limit hits.
- 8
Establish ongoing tuning: re-run Discovery on a cadence to catch new endpoints, refresh schemas as APIs change, and review rejection and abuse signals so controls track the API surface as it evolves.
Risk register
Risks to control
Schema Validation is enabled in block mode before real traffic is reviewed, rejecting valid but undocumented request shapes.
Start Schema Validation in log mode, review non-conforming requests per endpoint, correct the schema or the client, then promote to block.
Discovery misses internal or rarely called endpoints, leaving shadow APIs unprotected.
Reconcile Discovery output against documentation and source, and re-run Discovery on a cadence so new and seldom-used endpoints are added to Endpoint Management.
mTLS rollout breaks partner or mobile clients that cannot present a client certificate.
Inventory which clients can do mTLS, distribute and test certificates with partners first, and enforce mTLS per endpoint only after those clients are verified.
JWT Validation rejects valid tokens because issuer, audience, or signing-key configuration is wrong.
Configure the token configuration against the real issuer and JWKS, validate in log mode against live tokens, and confirm clock skew and key rotation handling before enforcing.
Sequence Mitigation blocks legitimate flows because the expected call order was modelled incorrectly.
Baseline real session sequences first, model the expected order from observed traffic, and run sequence rules in log mode before enforcing on sensitive flows.
Per-endpoint rate limits are set from guesswork and either throttle real clients or fail to stop abuse.
Derive thresholds from observed per-endpoint volume and client distribution, stage limits in log mode, and tune against analytics before enforcement.
Output
Useful deliverables
- API inventory from Discovery reconciled with documentation, with shadow and undocumented endpoints flagged.
- Endpoint Management labels classifying each endpoint by sensitivity, auth method, client type, and volume.
- Schema Validation configuration with OpenAPI schemas and a log-mode review of non-conforming requests.
- Client authentication plan covering mTLS scope and CA setup plus JWT Validation token configuration.
- Abuse-control configuration: per-endpoint rate limits, bot-signal alignment, and Sequence Mitigation rules where call order matters.
- Staged enforcement plan moving each control from log to block per endpoint with rollback notes.
- API Shield visibility setup — analytics, Logpush to SIEM, and alerts — plus a recurring Discovery, schema-refresh, and tuning cadence.
Keep reading
Related resources
FAQ
Frequently asked questions
Common questions teams ask when putting this resource into practice.
Where should an API Shield rollout start?
With Discovery and Endpoint Management. You cannot protect endpoints you have not enumerated and classified. Once the real API surface is mapped and labelled by sensitivity and client type, Schema Validation, authentication, and abuse controls can be scoped per endpoint.
What is the difference between Schema Validation, JWT Validation, and mTLS?
Schema Validation checks that each request matches the endpoint's OpenAPI definition. JWT Validation verifies the bearer token's signature and claims for token-authenticated endpoints. mTLS authenticates the client itself with a certificate, which suits machine-to-machine and partner traffic. They address request shape, token validity, and client identity respectively, and are usually layered.
When is Sequence Mitigation worth using?
When the order of API calls carries security meaning — for example a checkout that should only follow an add-to-cart, or a funds transfer that should follow authentication. Baseline the real sequences, model the expected order, and run in log mode before enforcing so legitimate flows are not blocked.
Can API Shield be enabled without breaking clients?
Yes, by staging. Every control — Schema Validation, JWT Validation, mTLS, rate limits, Sequence Mitigation — runs in log mode first so non-conforming or unauthenticated traffic is observed, not blocked. Each is then promoted to enforcement per endpoint as evidence and client readiness allow.
Nanosek
Protect your APIs
Nanosek can turn this resource into a practical delivery plan for your environment — with rollback planning, stakeholder alignment, and 24/7 managed operations support.