Cloudflare Access authenticates the edge, not your application

A field guide to Cloudflare Access applications, Service Auth, JWT verification, machine identity, Bypass, pricing, and deletion proof.

Cloudflare Access sits between a request and an origin. For a person, it turns an application URL into an identity check: Cloudflare redirects the browser to an identity provider, applies an Access policy, and issues a signed session token. For a machine, there is no login page. It must send a service credential on the first request, and the Access policy must explicitly accept that credential.

The distinction that decides the design:

Access proves that a request satisfied an edge policy. Your application still decides what that authenticated principal may do.

A service token can pass Access and still carry no human identity. A Bypass rule can make a path reachable while removing Access authentication and Access logging from that path. Deleting the application does not prove the service token was deleted, and deleting the token does not prove the application or policy disappeared. Those are separate objects with separate list and delete operations.

Evidence status

Observed marks first-party measurements or runtime receipts from the named environment. Derived marks arithmetic calculated from cited inputs. Specified marks vendor or standards documentation. Implemented and deployed name code and live-state evidence, respectively. Reproduced means the stated procedure was rerun. Externally attested marks operator reports; those reports show that an experience occurred, not that it is universal.

The request path, without product names hiding the mechanics

Stage	Human request	Machine request
1. Request arrives	Browser requests the protected hostname and path	HTTP client requests the same URL
2. Access checks credential	Looks for a valid `CF_Authorization` cookie	Looks for service-token headers or another non-human credential
3. No valid credential	Redirects to the Access login flow	Usually a `302` the client cannot use, or `401`/`403` when Service Auth handling is configured
4. Policy evaluation	Allow, Block, Bypass, or a more specific rule	Service Auth, mTLS, or Bypass
5. Origin request	Cloudflare forwards `Cf-Access-Jwt-Assertion`	Cloudflare forwards an application JWT after service authentication
6. Origin authorization	Verify signature, issuer and audience; map `email` or `sub` to an app role	Verify the same fields; map `common_name` to a synthetic machine principal

Access is not an origin firewall. Unless the origin is connected only through Cloudflare Tunnel or otherwise restricted to Cloudflare, an attacker may try to reach it directly and avoid the Access layer. Even when every request must pass Cloudflare, the origin still verifies the JWT. Cloudflare's application-token reference is blunt: validation of the header alone is insufficient because an unverified header can be spoofed.

Create one self-hosted application in the dashboard

Prerequisites: a Cloudflare account, a Zero Trust organization, a domain on Cloudflare, and an identity provider. The built-in one-time PIN flow is enough for a small first deployment; an organization using group rules should connect its existing SAML or OIDC provider and confirm the exact group claim before writing policy.

Current dashboard path:

Open Zero Trust.
Go to Access controls → Applications.
Select Add an application.
Choose Self-hosted.
Set Application name.
Under Session Duration, choose how long the application JWT remains valid.
Under Add public hostname, enter Subdomain, Domain, and optional Path. A path makes the Access application narrower than the hostname.
Under Access policies, create or attach a policy.
Choose the identity providers shown on the login page.
Save, then test one allowed identity and one denied identity before widening the selectors.

Access applications are deny-by-default. Creating the hostname without an Allow or Service Auth policy does not grant anyone access.

The four policy actions do different jobs:

Action	What a match means	Correct use	Dangerous misunderstanding
Allow	The request may continue after identity authentication	People selected by email, IdP group, country, device posture, or another identity rule	“Not blocked” does not mean allowed; unmatched users remain denied
Block	The matching request is denied	Carve a narrow denial out of a broader Allow rule	A Block rule alone does not make everyone else allowed
Bypass	Access enforcement is disabled for the matching traffic	A deliberately public webhook or health path whose own exposure is accepted	No Access identity, controls, or Access logs remain on that path
Service Auth	A non-IdP credential may pass	Service tokens or mutual TLS for automation	A service token is not a human and may not have `sub` or `email`

Policy order and selectors matter. Test with the policy tester, then make real HTTP requests. A green dashboard object is configuration evidence, not traffic evidence.

The same application and policy through the REST API

Use a Cloudflare API token scoped to Access: Apps and Policies Write. Keep the account id and API token in environment variables; neither belongs in shell history, an article, or a CI log.

curl -sS -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "content-type: application/json" \
  --data '{
    "name": "admin surface",
    "type": "self_hosted",
    "domain": "admin.example.com",
    "session_duration": "8h",
    "app_launcher_visible": false,
    "service_auth_401_redirect": true
  }'

Line 12, Column 1Shell Script

Capture result.id as ACCESS_APP_ID. Do not hand-type it.

curl -sS -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps/$ACCESS_APP_ID/policies" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "content-type: application/json" \
  --data '{
    "name": "named administrators",
    "decision": "allow",
    "precedence": 1,
    "include": [
      {"email_domain": {"domain": "example.com"}}
    ]
  }'

Line 12, Column 1Shell Script

The API response must say success: true. Follow it with a fresh GET of the exact application. A 201 proves creation, but the GET proves the stored hostname, policy and session settings are the ones you intended.

For infrastructure automation, create a service token separately:

curl -sS -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/service_tokens" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "content-type: application/json" \
  --data '{"name":"deploy smoke","duration":"720h"}'

Line 5, Column 1Shell Script

The client secret is returned once. Store it in the deployment secret store immediately. The token still does nothing until a policy accepts it:

curl -sS -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps/$ACCESS_APP_ID/policies" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "content-type: application/json" \
  --data '{
    "name": "deployment machine",
    "decision": "non_identity",
    "precedence": 2,
    "include": [{"any_valid_service_token": {}}]
  }'

Line 10, Column 1Shell Script

Cloudflare's API calls the non_identity decision Service Auth in the dashboard. That naming difference is worth writing in the runbook; otherwise an operator comparing JSON with the UI can think the wrong policy was created.

A service token is two secret headers and one policy

The normal first request carries:

curl -sS https://admin.example.com/health \
  -H "CF-Access-Client-Id: $ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $ACCESS_CLIENT_SECRET"

Line 3, Column 1Shell Script

Cloudflare checks the two values, evaluates a Service Auth policy, and forwards the request with Cf-Access-Jwt-Assertion. A successful request can also return a CF_Authorization cookie. If the application contains only Service Auth policies, Cloudflare requires the service token on subsequent requests too; the JWT cookie alone is not enough.

Access also supports a single custom header containing both values. That helps SaaS clients with one configurable authorization field. It does not help software with no custom-header extension point.

That limitation is common, not theoretical.

kennypy put Jellyfin behind Access. Google SSO worked in a browser, but the Findroid client could not add the two headers and became LAN-only. hippiuS hit the same shape with an MCP client calling ArgoCD: the request became a 302 to an SSO page a non-browser could not follow, or a 403. The ArgoCD CLI needed a general --header flag before it could work with this class of proxy authentication.

The rule: check the client's HTTP surface before choosing Access for the endpoint. “It can call HTTPS” is insufficient. It must be able to set two headers, one configured compound header, mTLS credentials, or an Access-aware token.

The service-token JWT has authority but may have no user

The recovered first-party probe created a temporary self-hosted application, added Service Auth, minted a temporary service token, and called a protected path. With valid headers, Access let the request reach the origin. The origin returned its own 404, which is the useful proof: the credential cleared the edge policy.

The redacted application-token payload had this shape:

json

{
  "type": "app",
  "iat": 1785041363,
  "exp": 1785043164,
  "iss": "https://<team-name>.cloudflareaccess.com",
  "sub": "",
  "aud": ["<application-audience>"],
  "common_name": "<service-token-client-id>"
}

Line 9, Column 1JSON

There was no email claim. sub was the empty string.

dataGriff documented the consequence in a CI smoke test: once Access was enforced, the service-token caller had no user id to own a review and no human admin standing. The correct repair is not to invent an email inside every handler. Map the verified service principal once, at the authentication seam:

function principalFromAccessClaims(claims) {
  if (claims.type === "app" && claims.common_name) {
    return {
      kind: "machine",
      id: `access-service:${claims.common_name}`,
      roles: ["deploy-smoke"],
    };
  }
  if (claims.email && claims.sub) {
    return {
      kind: "human",
      id: claims.sub,
      email: claims.email,
      roles: rolesForEmail(claims.email),
    };
  }
  throw new Error("Access token has no usable principal");
}

Line 18, Column 1JavaScript

The application authorizes deploy-smoke to do only the smoke-test operations. It does not promote every service token to administrator. common_name is useful only after the JWT signature, issuer and audience have passed.

Verify the JWT at the origin

Read Cf-Access-Jwt-Assertion. Cloudflare recommends that header because the cookie is not guaranteed to reach the origin. Then verify:

The signature against the team's JWKS.
alg is the expected RS256 algorithm.
iss equals the exact team-domain issuer.
aud contains the exact Access application audience tag.
exp and nbf permit the current time.
The resulting human or machine principal is authorized for this application action.

With jose:

import { createRemoteJWKSet, jwtVerify } from "jose";

const TEAM_DOMAIN = process.env.ACCESS_TEAM_DOMAIN;
const ACCESS_AUD = process.env.ACCESS_AUD;
const issuer = `https://${TEAM_DOMAIN}`;
const jwks = createRemoteJWKSet(
  new URL(`${issuer}/cdn-cgi/access/certs`),
);

export async function requireAccess(request) {
  const token = request.headers.get("Cf-Access-Jwt-Assertion");
  if (!token) return { ok: false, status: 401, error: "missing Access JWT" };

  try {
    const { payload, protectedHeader } = await jwtVerify(token, jwks, {
      issuer,
      audience: ACCESS_AUD,
      algorithms: ["RS256"],
    });
    return {
      ok: true,
      claims: payload,
      algorithm: protectedHeader.alg,
      principal: principalFromAccessClaims(payload),
    };
  } catch {
    return { ok: false, status: 403, error: "invalid Access JWT" };
  }
}

Line 29, Column 1JavaScript

Do not hard-code a PEM. The public endpoint carries the current signing key and the previous rotated key. The fresh read on this account returned two RSA signing keys, both RS256. A remote JWKS loader selects by kid and survives rotation.

Bypass is a public route, not machine authentication

A Bypass policy removes Access from matching traffic. Cloudflare does not apply Access security controls to it, and the request is not present in Access logs. That can be correct for a public payment webhook whose provider cannot send Access credentials, provided the handler verifies the provider's own signature and rejects replay.

It is not a shortcut for a private API.

lesbass reported a split application where the unauthenticated health endpoint worked while every company-scoped API call failed with RESPONSIBLE_USER_UNAVAILABLE. The Access identity existed, but it did not map to a company member. Opening more paths would hide the identity defect by removing authentication from them.

Use the narrowest path possible. Put a separate handler-level signature on a bypassed webhook. Do not Bypass /api/* because one vendor callback needs to be public.

Deleting one object proves nothing about the other two

An Access deployment usually creates at least three resources:

Resource	What deleting it removes	What remains
Access application	Hostname/path protection and attached application policies	Reusable policies and service tokens may remain
Application policy	One Allow, Block, Bypass or Service Auth decision	Application and credentials remain
Service token	That client id and secret	Application and Service Auth policy remain, ready to accept another valid token

The proof sequence is explicit:

curl -sS -X DELETE \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps/$ACCESS_APP_ID" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl -sS -X DELETE \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/service_tokens/$SERVICE_TOKEN_ID" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl -sS \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

curl -sS \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/service_tokens" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Line 15, Column 1Shell Script

Require HTTP success and Cloudflare success: true before examining either list. A 401, 403, or empty parse is not absence proof. The final lists must contain neither the exact id nor the exact temporary name.

The temporary measurement used for this page was rechecked at 2026-07-26T06:09:10Z. Both authenticated lists succeeded. Neither the application id/name nor the service-token id/name was present. Zero probe resources remained.

When a single bearer key is the better answer

This application's owner surface does not use Access. Its middleware accepts one owner key by request header or URL parameter, or a signed 60-day HttpOnly admin-session cookie minted after the key is entered once. An unauthenticated browser is redirected to the public login page. An unauthenticated machine request receives a bounded 401 JSON object.

That posture accepts a sharp trade: one strong secret has no person-level identity, no IdP offboarding and no device-posture check. In return, any HTTP client that can set one header can use it, the application controls the exact failure response, and machine calls do not depend on an SSO redirect.

For one owner and a closed automation surface, that can beat Access. For 20 administrators who need individual revocation and audit attribution, it does not.

Option	Best fit	Identity	Machine-client requirement	Verdict
Cloudflare Access	Several people, existing IdP, per-person revocation	Human email/groups; machine principal for service tokens	Custom headers, mTLS, or Access-aware client	Default for a shared admin UI
mTLS	Services or managed devices with certificate lifecycle	Certificate subject or mapped device	Client-certificate support	Strong machine auth; heavier issuance and rotation
One bearer key checked in the Worker	One owner, small fixed set of scripts	Shared principal only	One configurable header	Best simple answer when per-person identity adds no value
IP allow-list	Fixed corporate egress as one factor	Network location, not a person	Stable source IP	Use as a condition, not the only credential
Tunnel plus Access	Private origin that must not be directly reachable	Access identity plus private origin path	Browser login or service credential	Strongest Access topology for a self-hosted origin
Bypass plus handler signature	One third-party webhook	Provider key/signature	Provider-specific signed request	Correct for that path only

Seats and arithmetic

Cloudflare's current plan page says the Free plan is for teams under 50 users and costs $0. Pay-as-you-go is $7 per user per month. The page describes Remote Browser Isolation as an add-on but does not publish its current add-on price. A dated 2023 operator comparison recorded $10 per user per month; treat that as historical evidence, not today's quote.

Administrators	Access Free	Pay-as-you-go at $7/seat/month	Shared bearer key
1	$0	$7	$0 product fee
12	$0	$84	$0 product fee
49	$0	$343	$0 product fee
60	Plan choice required; outside “under 50” positioning	$420	$0 product fee, but 60 people sharing one key is indefensible
250	Not the free-plan fit	$1,750	Wrong architecture

The calculation is seats × $7. It excludes support, identity-provider cost, implementation time, and any separately quoted Remote Browser Isolation add-on. A bearer key has no Cloudflare seat line item, but secret rotation and the absence of individual attribution are costs; they are just paid in operator time and incident risk.

What administering Access feels like

The policy surface is capable. The console has drawn specific criticism. systemvoltage, otherwise positive about Cloudflare's main dashboard, described the Access/Zero Trust area as a separate application that took ten seconds and redirected repeatedly, with worse UI and thin documentation.

That report is dated 2022. Do not turn it into a claim about today's page speed. Keep the durable operational lesson: the person on call needs the API paths and curl proofs in the runbook, because a graphical console can be slow, moved, or unavailable.

The positive operator case is equally concrete. tbhb uses Tunnel plus Access to expose only the local-development endpoints that must be public, such as webhooks, while keeping the rest of the site behind Access. That is the product boundary working: narrow public ingress, authenticated private remainder, and no directly published origin.

Error, cause, repair

Symptom	Cause	Repair
`302` to `*.cloudflareaccess.com/cdn-cgi/access/login/...`	No accepted credential and the application is using interactive login behavior	Browser: complete the IdP flow. Machine: send a service token and add Service Auth, or enable the documented 401 response for Service Auth
`403` before the origin	Invalid service headers, no matching policy, wrong application path, or denied selector	Confirm both header names, list the application and policies, then test the exact hostname/path
Valid service token reaches origin but `sub` is empty	Service-token application JWT is non-human	Map verified `common_name` to a least-privilege synthetic machine identity
JWT signature verification fails	Wrong issuer, wrong audience, stale hard-coded key, altered token, or wrong algorithm	Fetch the team JWKS, select by `kid`, require RS256, exact issuer and exact application audience
Browser works; native client gets 302/403	Client cannot add Access service-token headers	Add a general custom-header option, use the single-header mode, mTLS, or do not put that endpoint behind Access
Health works; every scoped API call fails	Health is public/Bypass while authenticated principal is not mapped into app membership	Fix identity mapping at the auth seam; do not widen Bypass
Origin accepts a claimed Access header without cryptographic verification	Application trusts attacker-supplied text	Verify JWT signature, issuer, audience and time before reading identity
Temporary app appears deleted but token remains	Only the Access application was deleted	Delete the service token separately; require fresh successful lists for both collections

Three live receipts, with bounded claims

Access path. A temporary application protected a unique path. Plain HTTP returned 302 before Service Auth and 403 after the Service Auth policy existed. Correct service-token headers passed Access and reached the origin, which returned its own 404. The redacted JWT used RS256, had type: "app", an audience and common_name, an empty sub, and no email.

Signing keys. A fresh unauthenticated GET of the account's team JWKS returned HTTP 200, 4,914 JSON bytes and two RSA/RS256 signing keys. The published command uses a placeholder, not the real team name:

curl -sS "https://<team-name>.cloudflareaccess.com/cdn-cgi/access/certs" \
  | jq '{keys: [.keys[] | {kid, alg, kty, use}]}'

Line 2, Column 1Shell Script

This application's key-only admin gate. A fresh machine request with no credential:

curl -sS -D - https://miscsubjects.com/admin \
  -H 'accept: application/json'

Line 2, Column 1Shell Script

returned HTTP 401, application/json, and a 47-byte body with only error and login. A scan found no stack, trace, binding, database, exception or key marker. This proves the unauthenticated failure is bounded; it does not prove the shared-key posture has person-level identity.

Cleanup. Successful authenticated Access application and service-token lists proved the temporary ids and names absent. No 401, 403, or failed parse was treated as an empty list.

Access earns its complexity when identity changes the authorization decision. If every accepted caller is the same owner and every client already holds the same operational secret, one checked key is smaller and often more reliable. Once individual revocation, IdP groups or device posture matter, use Access, verify the JWT at the origin, and give machines a principal of their own.

This chapter is part of the Cloudflare account inventory. For the private-origin and Durable Object boundary, see Workers and Durable Objects.

References (23)

Authorization cookie — Cloudflare“When you protect a site with Cloudflare Access, Cloudflare checks every HTTP request bound for that site to ensure that the request has a valid `CF_Authorization` cookie.”
Application token — Cloudflare“Validation of the header alone is not sufficient — the JWT and signature must be confirmed to avoid identity spoofing.”
Validate JWTs — Cloudflare“We recommend validating the `Cf-Access-Jwt-Assertion` header instead of the `CF_Authorization` cookie, since the cookie is not guaranteed to be passed.”
Access policies — Cloudflare“The Bypass action in Cloudflare Access disables Access enforcement for specific traffic.”
Service tokens — Cloudflare“Make sure to set the policy action to Service Auth; otherwise, Access will prompt for an identity provider login.”
Add a self-hosted application — Cloudflare“Access applications are deny by default.”
Create an Access application — Cloudflare API“Adds a new application to Access.”
Create a service token — Cloudflare API“This is the only time you can get the Client Secret. If you lose the Client Secret, you will have to create a new Service Token.”
Zero Trust services plans — Cloudflare“$7 user / month”
Remote Browser Isolation — Cloudflare“Cloudflare Browser Isolation is available as an add-on for Cloudflare One plans.”
Cloudflare Tunnel — Cloudflare“Cloudflare Tunnel provides you with a secure way to connect your resources to Cloudflare without a publicly routable IP address.”
panva/jose — GitHub“`jose` is JavaScript module for JSON Object Signing and Encryption, providing support for JSON Web Tokens (JWT), JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), and JSON Web Key Set (JWKS).”
Add support for Cloudflare Access Service Tokens (Custom Headers) — GitHub — jarnedemeulemeester/findroid, Jul 20, 2025“While browser access works (via Google SSO), the app fails because it can’t pass the required authentication headers to bypass Cloudflare Access. This limits Findroid to LAN-only use”
Support custom HTTP headers on outbound ArgoCD API requests — GitHub — argoproj-labs/mcp-for-argocd, May 13, 2026“Requests bypass the proxy auth and get a 302 to the SSO page (which a non-browser MCP client can't follow) or a 403.”
Give Access service-token callers a usable identity — GitHub — dataGriff/outcome-app-pattern-whiskey, Jul 12, 2026“Access service-token JWTs carry an empty `sub` and no email, so a machine caller has no user id to write reviews by and no admin standing — the post-deploy smoke breaks the moment Access is enforced.”
Cloudflare Access blocker prevents Paperclip API operations — GitHub — lesbass/ai-newsroom, Jul 23, 2026“All Paperclip API calls fail with `RESPONSIBLE_USER_UNAVAILABLE` error due to Cloudflare Access authentication issues.”
Comment on Cloudflare's Access console — Hacker News, May 10, 2022“Well, except the Access/ZeroTrust app. Not sure why that's a different app that takes 10 seconds to redirect a bazillion times.”
Comment on Browser Isolation pricing — Hacker News, Apr 8, 2023“CloudFlare remote browsers is a $10/user/month add-on [2].”
Comment on Tunnel plus Access — Hacker News, Oct 22, 2024“I've been experimenting lately with CloudFlare Tunnel + Zero Trust Access as well for exposing only the endpoints I need from an application for local development like webhooks, with the rest of the site locked behind Access.”
Temporary Access request-path receipt — miscsubjects.com, Jul 26, 2026“302 before Service Auth; 403 after Service Auth; valid service token reached the origin's 404.”
Service application-token receipt — miscsubjects.com, Jul 26, 2026“RS256; type app; audience and common_name present; sub empty; email absent.”
Fresh JWKS and owner-gate receipt — miscsubjects.com, Jul 26, 2026“JWKS: HTTP 200, 4,914 bytes, two RSA/RS256 signing keys. /admin without a credential: HTTP 401, 47 bytes, keys error and login.”
Temporary resource deletion proof — miscsubjects.com, Jul 26, 2026“Both authenticated lists succeeded; exact application and service-token ids and names were absent.”

The system

Messaging

Ads and leads

Devices

Industries

Explore