1# Patterns & Use Cases
2 
3## Protect API with Schema + JWT
4 
5```bash
6# 1. Upload OpenAPI schema
7POST /zones/{zone_id}/api_gateway/user_schemas
8 
9# 2. Configure JWT validation
10POST /zones/{zone_id}/api_gateway/token_validation
11{
12  "name": "Auth0",
13  "location": {"header": "Authorization"},
14  "jwks": "{...}"
15}
16 
17# 3. Create JWT rule
18POST /zones/{zone_id}/api_gateway/jwt_validation_rules
19 
20# 4. Set schema validation action
21PUT /zones/{zone_id}/api_gateway/settings/schema_validation
22{"validation_default_mitigation_action": "block"}
23```
24 
25## Progressive Rollout
26 
27```
281. Log mode: Observe false positives
29   - Schema: Action = Log
30   - JWT: Action = Log
31 
322. Block subset: Protect critical endpoints
33   - Change specific endpoint actions to Block
34   - Monitor firewall events
35 
363. Full enforcement: Block all violations
37   - Change default action to Block
38   - Handle fallthrough with custom rule
39```
40 
41## BOLA Detection
42 
43### Enumeration Detection
44Detects sequential resource access (e.g., `/users/1`, `/users/2`, `/users/3`).
45 
46```javascript
47// Block BOLA enumeration attempts
48(cf.api_gateway.cf-risk-bola-enumeration and http.host eq "api.example.com")
49// Action: Block or Challenge
50```
51 
52### Parameter Pollution
53Detects duplicate/excessive parameters in requests.
54 
55```javascript
56// Block parameter pollution
57(cf.api_gateway.cf-risk-bola-pollution and http.host eq "api.example.com")
58// Action: Block
59```
60 
61### Combined BOLA Protection
62```javascript
63// Comprehensive BOLA rule
64(cf.api_gateway.cf-risk-bola-enumeration or cf.api_gateway.cf-risk-bola-pollution)
65and http.host eq "api.example.com"
66// Action: Block
67```
68 
69## Authentication Posture
70 
71### Detect Missing Auth
72```javascript
73// Log endpoints lacking authentication
74(cf.api_gateway.cf-risk-missing-auth and http.host eq "api.example.com")
75// Action: Log (for audit)
76```
77 
78### Detect Mixed Auth
79```javascript
80// Alert on inconsistent auth patterns
81(cf.api_gateway.cf-risk-mixed-auth and http.host eq "api.example.com")
82// Action: Log (review required)
83```
84 
85## Fallthrough Detection (Shadow APIs)
86 
87```javascript
88// WAF Custom Rule
89(cf.api_gateway.fallthrough_triggered and http.host eq "api.example.com")
90// Action: Log (discover unknown) or Block (strict)
91```
92 
93## Rate Limiting by User
94 
95```javascript
96// Rate Limiting Rule (modern syntax)
97(http.host eq "api.example.com" and
98 is_jwt_valid(http.request.jwt.payload["{config_id}"][0]))
99 
100// Rate: 100 req/60s
101// Counting expression: lookup_json_string(http.request.jwt.payload["{config_id}"][0], "sub")
102```
103 
104## Volumetric Abuse Response
105 
106```javascript
107// Detect abnormal traffic spikes
108(cf.api_gateway.volumetric_abuse_detected and http.host eq "api.example.com")
109// Action: Challenge or Rate Limit
110 
111// Combined with rate limiting
112(cf.api_gateway.volumetric_abuse_detected or
113 cf.threat_score gt 50) and http.host eq "api.example.com"
114// Action: JS Challenge
115```
116 
117## GraphQL Protection
118 
119```javascript
120// Block oversized queries
121(http.request.uri.path eq "/graphql" and
122 cf.api_gateway.graphql_query_size gt 100000)
123// Action: Block
124 
125// Block deep nested queries
126(http.request.uri.path eq "/graphql" and
127 cf.api_gateway.graphql_query_depth gt 10)
128// Action: Block
129```
130 
131## Architecture Patterns
132 
133**Public API:** Discovery + Schema Validation 2.0 + JWT + Rate Limiting + Bot Management  
134**Partner API:** mTLS + Schema Validation + Sequence Mitigation  
135**Internal API:** Discovery + Schema Learning + Auth Posture
136 
137## OWASP API Security Top 10 Mapping (2026)
138 
139| OWASP Issue | API Shield Solutions |
140|-------------|---------------------|
141| API1:2023 Broken Object Level Authorization | **BOLA Detection** (enumeration + pollution), Sequence mitigation, Schema, JWT, Rate Limiting |
142| API2:2023 Broken Authentication | **Auth Posture**, mTLS, JWT validation, Bot Management |
143| API3:2023 Broken Object Property Auth | Schema validation, JWT validation |
144| API4:2023 Unrestricted Resource Access | Rate Limiting, **Volumetric Abuse Detection**, **GraphQL Protection**, Bot Management |
145| API5:2023 Broken Function Level Auth | Schema validation, JWT validation, Auth Posture |
146| API6:2023 Unrestricted Business Flows | Sequence mitigation, Bot Management |
147| API7:2023 SSRF | Schema validation, WAF managed rules |
148| API8:2023 Security Misconfiguration | **Schema Validation 2.0**, Auth Posture, WAF rules |
149| API9:2023 Improper Inventory Management | **API Discovery**, Schema learning, Auth Posture |
150| API10:2023 Unsafe API Consumption | JWT validation, Schema validation, WAF managed |
151 
152## Monitoring
153 
154**Security Events:** `Security > Events` → Filter: Action = block, Service = API Shield  
155**Firewall Analytics:** `Analytics > Security` → Filter by `cf.api_gateway.*` fields  
156**Logpush fields:** APIGatewayAuthIDPresent, APIGatewayRequestViolatesSchema, APIGatewayFallthroughDetected, JWTValidationResult
157 
158## Availability (2026)
159 
160| Feature | Availability | Notes |
161|---------|-------------|-------|
162| mTLS (CF-managed CA) | All plans | Self-service |
163| Endpoint Management | All plans | Limited operations |
164| Schema Validation 2.0 | All plans | Limited operations |
165| API Discovery | Enterprise | 10K+ ops |
166| JWT Validation | Enterprise add-on | Full validation |
167| BOLA Detection | Enterprise add-on | Requires session IDs |
168| Auth Posture | Enterprise add-on | Security audit |
169| Volumetric Abuse Detection | Enterprise add-on | Traffic analysis |
170| GraphQL Protection | Enterprise add-on | Query limits |
171| Sequence Mitigation | Enterprise (beta) | Contact team |
172| Full Suite | Enterprise add-on | All features |
173 
174**Enterprise limits:** 10K operations (contact for higher). Preview access available for non-contract evaluation.
175 
176## See Also
177 
178- [configuration.md](configuration.md) - Setup all features before creating rules
179- [api.md](api.md) - Firewall field reference and API endpoints
180- [gotchas.md](gotchas.md) - Common issues and limits
181