A marketplace's own mobile app gets low Cloudflare bot scores on its checkout API; how do you use JA3 or JA4 fingerprints to let it through safely?
answer
- fingerprint the TLS handshake
- one app build, one ClientHello
- JA4 sorts the extensions
- scope the Skip, recheck each release
basics
~20 sA native app's TLS stack usually yields the same JA3 or JA4 fingerprint across devices. Find it in Security Analytics, then add a Skip rule matching cf.bot_management.ja4 together with the app's API host and path, placed before the score rule.
solid answer
~40 sBot Management can be more sensitive to mobile app traffic, because an API client making JSON calls looks automated. **JA3** and **JA4** fingerprint how a client opens its TLS connection (its ClientHello), so installs of one app build typically share a value, exposed as `cf.bot_management.ja3_hash` and `cf.bot_management.ja4` with the Enterprise add-on. Read the app's fingerprint in Security Analytics or Bot Analytics by filtering on its API path, then add a custom rule with *Skip* that matches that JA4 **and** the API hostname and path, ordered before the score rule, rather than skipping it everywhere. Prefer JA4: it sorts ClientHello extensions, so it stays stable where JA3 splinters. A fingerprint names a TLS client implementation, not a user, so recheck it after each release that changes the networking stack and keep the API's own authentication.
code
plaintext · 5 linesRule 1 - action Skip (all remaining custom rules)
(http.host eq "api.example.com" and starts_with(http.request.uri.path, "/v1/checkout") and cf.bot_management.ja4 in {"<app-build-ja4-a>" "<app-build-ja4-b>"})
Rule 2 - action Block
(starts_with(http.request.uri.path, "/v1/checkout") and cf.bot_management.score lt 30 and not cf.bot_management.verified_bot)go deeper
Recall that JA3 and JA4 fingerprint a client's TLS handshake, that they need the Bot Management add-on, and that one app build usually shares one value.
Explain why JA4 is steadier than JA3, which fields and Worker properties expose them, and when they come back empty.
Build the exception from analytics, scope it to the app's host and path, order it before the score rule, and keep authentication and rate limits as the real controls.
Decide how first-party clients are recognised at the edge: fingerprints, attestation or authentication, who maintains the list across releases, and what an exception may skip.
## Why the app scores low The marketplace's mobile app talks to `api` endpoints with plain JSON requests: no page loads, no injected JavaScript, often no cookies. To Bot Management that looks a lot like a script, and Cloudflare notes that bot detection can be more sensitive to mobile traffic. The result is real customers' checkout calls scoring under 30 and running into the rules written for automated buyers. Lowering the threshold for everyone would let the bots back in; the better tool is a signal that separates **this** app from other automation. ## What JA3 and JA4 capture A **JA3** or **JA4 fingerprint** describes how a client initiates a TLS connection: the versions, cipher suites, extensions and other parameters in its ClientHello. Each kind of client (a browser, a scripting library, a mobile app built on a particular networking stack) has distinct connection characteristics, so the fingerprint is a stable identifier across destination IPs, ports and certificates. Mobile app traffic often produces the same JA3 or JA4 across devices and users. - **JA4** improves on JA3 by sorting ClientHello extensions before fingerprinting. Clients that vary extension order no longer splinter into many values, so modern browser traffic groups into far fewer fingerprints. - Both are available only to Enterprise customers with **Bot Management**, as the fields `cf.bot_management.ja3_hash` and `cf.bot_management.ja4`, in Workers as `request.cf.botManagement.ja3Hash` and `request.cf.botManagement.ja4`, and in Bot Analytics, Security Analytics, the GraphQL API and logs. - **JA4 Signals** add aggregate statistics per fingerprint over the last hour, such as how often it behaves like a browser, for code that wants more than an exact match. ## When the fields are empty The fingerprint is computed during the TLS handshake, so it can be null or empty: - on plain HTTP, where there is no TLS handshake; - on connections that use **TLS session resumption**, because after the first full handshake no new fingerprint is calculated; - on some Worker subrequests, for example to a zone internal to Cloudflare or to a third-party origin; - when Bot Management itself is skipped for the request. Worker code that reads `ja4` must therefore handle a missing value, and a rule that requires a fingerprint match fails closed for resumed sessions; the score rules still apply to those requests. Under `wrangler dev`, the local `request.cf` object carries placeholder bot data with no `ja4` at all, so the missing-value branch is the first one a Worker exercises. Treat an absent fingerprint as unknown, never as a match, so a client cannot qualify for the exception by stripping what the rule looks for. ## Building the exception 1. In Security Analytics, filter on the app's API hostname and checkout path, and group by JA4. The app's builds show as a handful of dominant values with app-like user agents and normal request rates. 2. Confirm the value is specific to the app: compare the same fingerprint's traffic on browser pages and other paths, and check how much of the app's checkout traffic arrives with no fingerprint at all, because those requests will not match the exception. 3. Create a custom rule matching the JA4 **and** the API host and path, with *Skip* for the remaining custom rules, and order it before the score-based rules. 4. Keep the other layers: the app's own authentication, and rate limiting rules on checkout, still apply to requests that match. 5. After each app release, and after operating-system updates that change the TLS stack, check analytics for new fingerprints and add them before old builds fade out. ## What a fingerprint does not prove A fingerprint identifies a TLS client implementation, not a person or an account. Any software built on the same library, or deliberately shaped to resemble it, presents the same value. That is why the *Skip* stays scoped to the API paths the app uses, and why it exempts only the bot-score rules rather than every security feature. Cloudflare also suggests the opposite approach: keeping the app in scope with lower thresholds for its user agent, blocking scores below 2 and challenging the rest below 30. A challenge only helps where the client can render it, which a native JSON call usually cannot, so for the checkout API the scoped fingerprint exception is usually the cleaner fix.
- Why might the app's JA4 suddenly stop matching the Skip rule?The fingerprint follows the TLS stack, not the app's name. A release that updates the networking library, or an operating-system update for apps that use the system TLS stack, changes the ClientHello and therefore the JA4. Keep the list of current values in the rule, watch analytics for new fingerprints on the API path after each release, and add them before older builds disappear.
- Why is JA4 usually a better allowlist key than JA3?JA4 sorts ClientHello extensions before fingerprinting, so a client that varies extension order still yields one value, while its JA3 hash splinters into many. Fewer, steadier values make an allowlist shorter and less brittle. Both are TLS-only and both are empty on resumed sessions or plain HTTP.
- A JA4 fingerprint identifies one device, so matching it authenticates the user.
- Skip every security feature for the app's fingerprint across the whole zone.
- JA3 and JA4 are available on every plan from Pro upwards.
- A fingerprint never changes, so the rule can be written once and forgotten.
- Every request over TLS is guaranteed to carry a JA4 value.