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.

Session identifiers

To set up session identifiers

Create a Schema Profile

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.

Enable the Sensitive Data Detection ruleset and accompanying rules

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.

:::note Sensitive Data Detection requires a separate subscription. Contact your account team if your plan does not include this feature. :::

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.

Manage operations

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.

After collecting enough qualifying traffic, you can request an ad-hoc schema learning run for the entire zone.

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

Add rate limits to your most sensitive endpoints

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.

Export a learned schema

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.

View and configure Sequence Analytics

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.

Additional configuration

Set up JSON Web Tokens (JWT) validation

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.

Set up GraphQL malicious query protection

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.

Mutual TLS (mTLS) authentication

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.