Get started with API Shield

API Shield protects your APIs by discovering endpoints, validating request schemas, and detecting abuse patterns. This guide walks through the initial setup from configuring session identifiers to enabling advanced protections.

While not strictly required, it is recommended that you configure your session identifiers when getting started with API Shield. When Cloudflare inspects your API traffic for individual sessions, we can offer more tools for visibility, management, and control.

If you are unsure of the session identifiers that your API uses, consult with your development team.

Session identifiers should uniquely identify API clients. A common session identifier for API traffic is the Authorization header. When a JSON Web Token (JWT) is used by the API for client authentication, its value may change over time. You can use a claim value inside the JWT such as sub or email as a session ID to uniquely identify the session over time.

If your API uses the Authorization header on more than 1% of successful requests to your zone, Cloudflare will automatically set it as the API Shield session identifier.

You must have specific entitlements to configure session identifiers or cookies as a form of identifiers, such as an Enterprise subscription, for features such as API Discovery, Sequence Mitigation or rate limiting recommendations, and to see results in Sequence Analytics and Authentication Posture.

After setting up session identifiers and allowing some time for Cloudflare to learn your traffic patterns, you can view your per endpoint and per session rate limiting recommendations, as well as enforce per endpoint and per session rate limits by creating new rules. Session identifiers will allow you to view API Discovery results from session ID-based discovery and session traffic patterns in Sequence Analytics.

Application Profiles provides one Schema Profile with two sources. Schema Learning derives a profile from traffic, while Schema Validation uses an uploaded OpenAPI schema.

Both sources provide an always-on detection after their profile becomes available. Mitigation requires a separate WAF Custom Rule.

If you maintain an OpenAPI schema, follow the Schema Validation upload procedure. API Shield remains the reference for OpenAPI compatibility, schema governance, and automation.

API Shield works with the Cloudflare WAF Sensitive Data Detection ruleset to identify API endpoints that return sensitive data, such as social security or credit card numbers, in their HTTP responses. Review these endpoints to verify that sensitive data is only returned where expected.

You can identify endpoints returning sensitive data by selecting the icon next to the path in a row. Expand the endpoint to see details on which rules were triggered and view more information by exploring events in Firewall Events.

Web Assets continuously discovers operations from traffic. An operation represents an endpoint by HTTP method, hostname pattern, and path pattern.

You can also add operations manually under Web Assets > Operations. Discovery and manual creation only add inventory entries.

To start Schema Learning, select Learn profile from the operation overflow menu. Review the learned schema through View details > Security overview.

For the complete workflow and traffic thresholds, refer to Get started with Application Profiles.

Rate limiting rules allow you to define rate limits for requests matching an expression, and choose the action to perform when those rate limits are reached.

API Shield generates rate limit recommendations for each endpoint based on your session identifiers. These recommendations are scoped per endpoint and per session rather than applied across your entire site or based on IP address.

Per-session rate limits track traffic from individual visitors during their session to a specific endpoint. This reduces false positives from broadly scoped rules while still limiting abusive traffic.

Learned schemas include the hostname, all endpoints by host, method, and path, and detected path variables (for example, /users/{id}). They can also include detected query parameters and their format. You can optionally include rate limit threshold recommendations.

You can export your learned schemas in the Cloudflare dashboard or via the API.

Exporting creates an OpenAPI v3.0.0 file. To use a fixed profile, upload that file through Schema Validation.

Sequence Analytics identifies common patterns of API requests for example, a user checking their account balance before initiating a funds transfer.

Sequences are ranked by precedence score, which measures how likely specific API requests are to occur together in a consistent order. High-scoring sequences contain API requests that are likely to be preceded by the other operations in the sequence.

Sequence mitigation allows you to enforce request patterns for authenticated clients communicating with your API. Use Sequence Analytics to identify the sequences your API clients follow, then apply API Shield protections (rate limiting, Schema validation, JWT validation, and mTLS) to the endpoints in your high-scoring sequences. Verify the expected endpoint order with your development team.

For more information, refer to Detecting API abuse automatically using sequence analysis blog post.

JSON Web Tokens (JWT) validation verifies that tokens sent by clients have not been tampered with and have not expired. Configure JWT validation using the Cloudflare dashboard or API.

If your origin uses GraphQL, you may consider setting limits on GraphQL query size and depth.

GraphQL malicious query protection scans GraphQL traffic for queries with excessive nesting or size that could overload your origin and result in a denial of service. You can create rules that set maximum query depth and size to block these queries before they reach your origin.

For more information, refer to the blog post .

If you operate an API that requires or would benefit from an extra layer of protection, you may consider using Mutual TLS (mTLS).

Mutual TLS (mTLS) authentication requires both the client and server to verify each other's identity using certificates. In standard TLS, only the server proves its identity. mTLS adds client verification, which is useful for devices like IoT hardware that do not authenticate via an identity provider.