--- title: Authenticate coding agents description: Grant coding agents like Claude Code, OpenCode, and Windsurf access to resources protected by Cloudflare Access using cloudflared or service tokens. image: https://developers.cloudflare.com/zt-preview.png --- > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/cloudflare-one/llms.txt > Use this file to discover all available pages before exploring further. [Skip to content](#%5Ftop) ### Tags [ AI ](https://developers.cloudflare.com/search/?tags=AI)[ Authentication ](https://developers.cloudflare.com/search/?tags=Authentication) # Authenticate coding agents Coding agents such as Claude Code, OpenCode, and Windsurf often need to reach resources protected by [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/access-controls/). When a resource is behind Access, unauthenticated requests receive a redirect or `403` error instead of the expected response. Your agent needs a way to authenticate before it can reach the resource. This page covers two authentication methods: * [**cloudflared**](#use-cloudflared) — authenticates under your user identity. Use for interactive development where you can complete a browser login. * [**Service tokens**](#use-service-tokens) — authenticates with a static credential pair. Use for headless or automated workflows where no browser is available. Note Cloudflare Access also supports Managed OAuth for protected resources, which you can use to grant authorization to coding agents. ## Use cloudflared With `cloudflared`, your agent authenticates under your user identity. On first use, `cloudflared` opens a browser window for an interactive login. After that, the session persists for the [session duration](https://developers.cloudflare.com/cloudflare-one/access-controls/access-settings/session-management/) configured for the application. After the session expires, the next request requires a new browser login. ### Prerequisites [Download and install cloudflared](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/). ### Make requests with cloudflared access curl For direct requests to a protected resource, use `cloudflared access curl`. This handles authentication automatically and does not require token management. Terminal window ``` cloudflared access curl https://example.com/api/endpoint ``` If this is the first request in a session, `cloudflared` opens a browser for the user to authenticate. Prompt the user to complete the login if needed. ### Use a reusable token Some agents make HTTP requests using their own client libraries instead of calling `cloudflared` directly. In this case, log in to get a token and pass it as a header: Terminal window ``` CF_TOKEN=$(cloudflared access login https://example.com) curl --header "cf-access-token: $CF_TOKEN" https://example.com/api/endpoint ``` The token is valid for the session duration configured for the application. For more information, refer to [Connect through Access using a CLI](https://developers.cloudflare.com/cloudflare-one/tutorials/cli/) and [Client-side cloudflared](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/non-http/cloudflared-authentication/). ## Use service tokens Service tokens are static credential pairs that authenticate requests without a browser login. Use them for automated workflows where no user is present. 1. [Create a service token](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/#create-a-service-token) and save the **Client ID** and **Client Secret**. 2. In the Access application's policy configuration, add a [Service Auth policy](https://developers.cloudflare.com/cloudflare-one/access-controls/policies/#service-auth). This policy type accepts service token credentials instead of requiring an identity provider login. Use the **Service Token** selector and select the token you created. | Action | Rule type | Selector | Value | | ------------ | --------- | ------------- | ---------------- | | Service Auth | Include | Service Token | Your agent token | 3. Store the Client ID and Client Secret in a secure location on your machine that your agent can read. 4. Include both values as headers in requests to the protected resource: Terminal window ``` curl --header "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \ --header "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \ https://example.com/api/endpoint ``` For more information, refer to [Service tokens](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/). ## Configure your agent Add an `AGENTS.md` file to your project root with the following skill definition. This instructs coding agents to automatically detect Cloudflare Access-protected resources and authenticate using the standard OAuth 2.0 flow with PKCE (RFC 9728). ``` --- name: access-oauth description: "Detect Cloudflare Access-protected websites and authenticate via the standard OAuth 2.0 flow (RFC 9728 resource metadata, dynamic client registration, authorization code + PKCE)" license: MIT compatibility: opencode metadata: category: authentication audience: developers --- # Access OAuth Authentication Authenticate to Cloudflare Access-protected resources using standard OAuth 2.0 (resource metadata discovery, dynamic client registration, authorization code with PKCE). ## When to Use Use this skill when: - You need to access a URL that returns HTTP 401 - The response contains a `www-authenticate: Bearer` header with a `resource_metadata` URL - The resource metadata indicates it is a Cloudflare Access-protected resource - You want to authenticate interactively through the user's IdP ## Step 1: Detect a Protected Resource Make a request and inspect the response headers: ```bash curl -sI -L 2>&1 ``` Look for a **401** response with a `www-authenticate` header like: ``` www-authenticate: Bearer realm="OAuth", error="invalid_token", error_description="Missing or invalid access token", resource_metadata="https:///.well-known/cloudflare-access-protected-resource/" ``` If you see this header, the site supports the OAuth flow. Proceed to Step 2. The JSON body of the 401 will also contain: ```json { "error": "invalid_token", "error_description": "Missing or invalid access token", "resource_metadata": "https:///.well-known/cloudflare-access-protected-resource/" } ``` ### If No `www-authenticate` Header If the 401 does not include `www-authenticate` with `resource_metadata`, the site may not support this OAuth flow. Fall back to `cloudflared access curl` or browser-based authentication. ## Step 2: Fetch Resource Metadata Fetch the resource metadata URL from the `www-authenticate` header: ```bash curl -s https:///.well-known/cloudflare-access-protected-resource/ ``` Expected response: ```json { "resource": "https://", "protected": true, "team_domain": ".cloudflareaccess.com", "authorization_servers": ["https://.cloudflareaccess.com"], "authentication_method": "cloudflared", "authentication_method_description": "Use `cloudflared access curl`...", "authentication_method_documentation": "https://developers.cloudflare.com/cloudflare-one/tutorials/cli/" } ``` Extract the **authorization server** URL from `authorization_servers[0]` (e.g. `https://.cloudflareaccess.com`). ## Step 3: Fetch OAuth Authorization Server Metadata ```bash curl -s https://.cloudflareaccess.com/.well-known/oauth-authorization-server ``` Expected response: ```json { "issuer": ".cloudflareaccess.com", "authorization_endpoint": "https://.cloudflareaccess.com/cdn-cgi/access/oauth/authorization", "token_endpoint": "https://.cloudflareaccess.com/cdn-cgi/access/oauth/token", "response_types_supported": ["code"], "response_modes_supported": ["query"], "grant_types_supported": ["authorization_code", "refresh_token"], "token_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", "none" ], "revocation_endpoint": "https://.cloudflareaccess.com/cdn-cgi/access/oauth/revoke", "registration_endpoint": "https://.cloudflareaccess.com/cdn-cgi/access/oauth/registration", "code_challenge_methods_supported": ["S256"] } ``` Verify that: - `"none"` is in `token_endpoint_auth_methods_supported` (allows public clients) - `"authorization_code"` is in `grant_types_supported` - `"S256"` is in `code_challenge_methods_supported` - A `registration_endpoint` is present Extract the **registration_endpoint**, **authorization_endpoint**, and **token_endpoint**. ## Step 4: Dynamic Client Registration Register a public OAuth client: ```bash curl -s -X POST \ -H "Content-Type: application/json" \ -d '{ "redirect_uris": ["http://localhost:8400/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code"], "response_types": ["code"], "resource": "https://" }' ``` Expected response: ```json { "client_id": "", "redirect_uris": ["http://localhost:8400/callback"], "grant_types": ["authorization_code"], "response_types": ["code"], "token_endpoint_auth_method": "none", "registration_client_uri": "...", "client_id_issued_at": 1234567890 } ``` Save the **client_id**. ## Step 5: Generate PKCE Challenge Generate a code verifier and S256 challenge. Ensure the challenge starts with an alphanumeric character to avoid URL parsing issues: ```bash while true; do CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=' | tr '/+' '_-') CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr -d '=' | tr '/+' '_-') if [[ "$CODE_CHALLENGE" =~ ^[a-zA-Z0-9] ]]; then break fi done ``` **Important**: The code challenge MUST start with `[a-zA-Z0-9]`. A leading `-` or `_` can cause URL parameter parsing failures on the authorization server. ## Step 6: Authorization Code Flow with Local Callback Start a local HTTP server to catch the callback, then direct the user to the authorization URL. ### Build the Authorization URL ``` ? client_id=& redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Fcallback& response_type=code& code_challenge=& code_challenge_method=S256& resource= ``` ### Start the Callback Listener and Prompt the User Run a Python HTTP server on port 8400 that captures the authorization code: ```python python3 -c ' import http.server, urllib.parse class Handler(http.server.BaseHTTPRequestHandler): def do_GET(self): parsed = urllib.parse.urlparse(self.path) params = urllib.parse.parse_qs(parsed.query) if "code" in params: code = params["code"][0] with open("/tmp/oauth_code.txt", "w") as f: f.write(code) self.send_response(200) self.send_header("Content-Type", "text/html") self.end_headers() self.wfile.write(b"

Got it!

Authorization code received. You can close this tab.

") print(f"CODE={code}", flush=True) elif "error" in params: err = params.get("error", [""])[0] desc = params.get("error_description", [""])[0] self.send_response(200) self.send_header("Content-Type", "text/html") self.end_headers() self.wfile.write(f"

Error

{err}: {desc}

".encode()) print(f"ERROR: {err} - {desc}", flush=True) else: self.send_response(400) self.end_headers() self.wfile.write(b"Unexpected request") print(f"Unexpected: {self.path}", flush=True) import threading threading.Thread(target=self.server.shutdown).start() def log_message(self, format, *args): pass print("Listening on http://localhost:8400 ...", flush=True) print("Open the authorization URL in your browser.", flush=True) http.server.HTTPServer(("", 8400), Handler).serve_forever() ' ``` **Important**: Use a timeout of at least 120000ms for this bash command since the user needs time to authenticate in the browser. Tell the user to open the authorization URL in their browser. After they authenticate with their IdP, the browser will redirect to `http://localhost:8400/callback?code=`, the server will capture it and shut down. ## Step 7: Exchange Code for Token ```bash curl -s -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "code=" \ -d "client_id=" \ -d "redirect_uri=http://localhost:8400/callback" \ -d "code_verifier=" ``` Expected response: ```json { "access_token": "oauth:", "token_type": "bearer", "expires_in": 900, "scope": "", "resource": "https:///", "refresh_token": "oauth:" } ``` Save the **access_token** and **refresh_token**. ## Step 8: Access the Protected Resource ```bash curl -s https:/// \ -H "Authorization: Bearer " ``` This should now return the actual content behind Cloudflare Access. ## Step 9: Refresh the Token (if needed) If the access token expires (default 900 seconds), use the refresh token: ```bash curl -s -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=refresh_token" \ -d "refresh_token=" \ -d "client_id=" ``` ## Quick Reference: Full Flow Summary ``` 1. curl -sI # Detect 401 + www-authenticate header 2. curl -s # Get authorization server 3. curl -s /.well-known/oauth-authorization-server # Get endpoints 4. POST # Register public client 5. Generate PKCE code_verifier + challenge # S256, alphanumeric start 6. Start localhost:8400 listener # Catch callback 7. User opens authorization URL # Browser-based IdP auth 8. POST # Exchange code for token 9. curl -H "Authorization: Bearer " # Access resource ``` ## Troubleshooting | Problem | Cause | Fix | | ------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `code_challenge_method must be S256 for public clients` | Code challenge starts with `-` or `_`, corrupting the URL parameter | Regenerate until challenge starts with `[a-zA-Z0-9]` | | `invalid_grant` on token exchange | Code expired or verifier mismatch | Redo the auth flow; codes are single-use and short-lived | | 401 after using token | Token expired (default 15 min) | Use refresh token to get a new access token | | No `www-authenticate` header | Site doesn't support OAuth resource metadata | Fall back to `cloudflared access curl` or browser auth | | No `registration_endpoint` in AS metadata | Dynamic registration not enabled | Must use a pre-registered client or different auth method | | Port 8400 already in use | Previous listener didn't shut down | Kill the process or use a different port (update redirect_uri accordingly) | ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/cloudflare-one/","name":"Cloudflare One"}},{"@type":"ListItem","position":3,"item":{"@id":"/cloudflare-one/access-controls/","name":"Access controls"}},{"@type":"ListItem","position":4,"item":{"@id":"/cloudflare-one/access-controls/authenticate-agents/","name":"Authenticate coding agents"}}]} ```