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 identifier to uniquely identify the session over time.

If no session identifiers are configured and the Authorization header appears on more than 1% of eligible sampled client requests with 2xx responses, Cloudflare automatically configures that header as the API Shield session identifier. Cloudflare does not overwrite an existing session identifier configuration.

An API Shield subscription or eligible API Shield trial is required to configure session identifiers, including cookie-based identifiers. Configured identifiers can provide optional evidence for API Discovery, and are used by Sequence Mitigation, rate limiting recommendations, Sequence Analytics, and Authentication Posture.

You can configure up to 10 session identifiers.

API Shield generates rate limiting recommendations for eligible saved operations. Recommendations require API Shield access, a configured session identifier that matches operation traffic, sufficient data, and completed processing. After these requirements are met, you can view per-operation and per-session recommendations and create rate limiting rules.

Discovery can use configured session identifiers as one signal when identifying API traffic. Session identifiers also support session traffic analysis 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 eligible saved operations. Recommendations require API Shield access, a configured session identifier that matches operation traffic, sufficient data, and completed processing. These recommendations are scoped per operation 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.

A learned-schema export is a point-in-time OpenAPI snapshot for a selected hostname. It includes learned operations by method and path and detected path variables (for example, /users/{id}). It can also include detected query parameters, their formats, and rate limit recommendations.

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

The export uses OpenAPI v3.0.0. 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.