Use Cloudflare

capability_id: cloudflare.use
display_name: Use general Cloudflare API relay
ui_capability_key: use_cloudflare_relay
scope: cloudflare:use
endpoint:
  method: POST
  path: /cloudflare/request
operation: cloudflare.request
billable: true
environment: none
credential:
  name: CLOUDFLARE_API_TOKEN
  kind: encrypted_provider_credential

Purpose and authorization

The cloudflare:use scope authorizes an authenticated application to send bounded native Cloudflare REST API requests through Gateman. Gateman authenticates the application, checks the scope, retrieves the application's encrypted CLOUDFLARE_API_TOKEN, injects bearer authentication, executes the request against Cloudflare API v4, and returns the bounded native response.

Cloudflare remains authoritative for account, zone, resource, and operation permissions. Gateman does not create Cloudflare permission scopes and does not replace Cloudflare's API-token or account authorization model.

This is a provider-specific HTTP relay, not an infrastructure-as-code system, Cloudflare resource manager, generic workflow engine, or Cloudflare SDK abstraction. It does not automatically discover resources, paginate results, retry requests, reconcile mutations, or interpret Cloudflare policy results. The application must use Contract v1 and hold cloudflare:use.

Implementation contract

POST /cloudflare/request
Content-Type: application/json
X-GM-App: app_...
X-GM-Ts: 1710000000
X-GM-Sig: <Contract-v1-signature>
X-GM-Idempotency-Key: optional-gateman-key

The outer request is authenticated with Contract v1. The optional X-GM-Idempotency-Key is part of the signed Contract v1 input, but this capability has no Gateman replay ledger and does not deduplicate or make a Cloudflare request safe to repeat. Cloudflare endpoint-specific semantics, if any, remain the provider's responsibility.

The outer JSON body contains the native Cloudflare request envelope. It is validated by Gateman and then translated only into the fixed Cloudflare API v4 origin plus the supplied relative path, encoded query, supported headers, and body.

The Official PHP, Node.js, Python, and Go clients all support this generic authenticated request contract and can call /cloudflare/request. No Cloudflare-specific Gateman client helper is required; agents must not invent provider-specific helper methods.

Request schema

Unknown top-level fields are ignored by the current validator. Integrations should send only the documented fields. Invalid JSON, invalid field types, unsupported methods, invalid paths, invalid headers, invalid base64, and oversized bodies are rejected before the provider request.

Fixed destination and path

Gateman always uses:

https://api.cloudflare.com/client/v4

The caller cannot select an origin, host, scheme, port, proxy, redirect destination, or absolute URL. Supply only the relative path. Put parameters in query; do not append ? or a raw query string to path.

Query encoding

query is encoded with PHP RFC 3986 query encoding and appended to the validated path. The encoded query is limited to 2,048 bytes independently of the path. Array values use the serializer's indexed/bracket representation. The field is a structured map, not a raw query string, and duplicate query keys cannot be represented independently.

Accepted request headers

The caller may provide only these headers, with case-insensitive names:

• Accept
• Content-Type
• If-Match
• If-None-Match
• Prefer
• X-Audit-Log

Header values must be strings and must not contain carriage returns or line feeds. The total caller-provided header name/value data is limited to 16 KiB. Authorization, Host, Cookie, proxy headers, content-length and transfer framing headers, and arbitrary Cloudflare headers are rejected. Gateman adds Authorization: Bearer ... from the protected application credential; the caller cannot replace it.

Body serialization

• A string with body_encoding: utf8 is forwarded as supplied.
• A JSON object or array is serialized with unescaped slashes and Unicode.
• A string with body_encoding: base64 is strictly decoded before forwarding.
• The decoded body must be no larger than 1 MiB (1,048,576 bytes).
• A non-empty body with no Content-Type receives Content-Type: application/json.
• A caller-provided accepted Content-Type is preserved.

The nested body is not parsed for Cloudflare semantics after serialization. Cloudflare validates the native JSON document, form, or other representation. Multipart form-data and arbitrary binary upload contracts are not supported by this envelope.

Cloudflare-native compatibility

This relay forwards native Cloudflare REST requests; it does not expose an operation-name or resource abstraction. Representative control-plane families that fit the contract include:

These are compatibility examples, not a Gateman allowlist or a guarantee that every Cloudflare operation is representable. Cloudflare's current API documentation, token permissions, account context, and resource state remain authoritative.

Administrative examples

The following are illustrative nested request envelopes. They use placeholders, not real account, zone, record, ruleset, or application identifiers. Each is sent as the authenticated body of POST /cloudflare/request.

List accounts

{
  "method": "GET",
  "path": "/accounts",
  "query": {
    "page": 1,
    "per_page": 50
  }
}

Inspect DNS records

{
  "method": "GET",
  "path": "/zones/zone_example_id/dns_records",
  "query": {
    "page": 1,
    "per_page": 100,
    "type": "A"
  },
  "headers": {
    "Accept": "application/json"
  }
}

Update a DNS record

{
  "method": "PATCH",
  "path": "/zones/zone_example_id/dns_records/record_example_id",
  "body": {
    "content": "192.0.2.10",
    "name": "www.example.com",
    "proxied": true,
    "ttl": 300,
    "type": "A"
  }
}

Because body is an array, Gateman serializes this example as JSON and adds Content-Type: application/json. Cloudflare must authorize the mutation, and the application should read the record afterward to verify the resulting state.

Inspect a ruleset

Inspect a ruleset collection:

{
  "method": "GET",
  "path": "/zones/zone_example_id/rulesets",
  "query": {
    "per_page": 100,
    "cursor": "<cursor_from_previous_response>"
  }
}

Inspect one existing ruleset:

{
  "method": "GET",
  "path": "/zones/zone_example_id/rulesets/ruleset_example_id"
}

Inspect an existing ruleset before modifying it. Cloudflare ruleset update operations may replace the existing rule collection, so construct mutations using the exact provider API semantics and verify the resulting configuration.

Live account-discovery compatibility

Live verification through the deployed Gateman route confirmed that an appropriately permitted bearer API token can successfully call Cloudflare's account-list endpoint and then retrieve account details using the returned account identifier. Token verification also succeeded.

This conclusion is about the tested bearer-token configuration and route compatibility. It is not a universal statement about every token or account. Cloudflare token permissions still determine whether account discovery and subsequent account-scoped operations are authorized. Do not add a legacy X-Auth-Email or X-Auth-Key requirement to an integration based on older Cloudflare examples; Gateman supplies the configured bearer token.

Workers and large-transfer boundary

Workers route and settings requests that fit this JSON/HTTP contract can use the relay. This capability does not provide a general Workers script or static asset deployment transport. In particular, do not assume that multipart uploads, streaming uploads, large script bundles, large asset transfers, or deployment-specific upload protocols fit the relay.

Use a provider-native or dedicated transfer path when Cloudflare's Workers operation requires multipart, streaming, a large body, or a deployment protocol outside this request envelope. Do not work around the relay's limits by splitting or replaying a mutation without understanding the provider's semantics.

Response contract

For a provider response within the transport limit, Gateman returns the native Cloudflare HTTP status and raw response body. There is no universal Gateman success envelope and no automatic JSON, XML, text, or binary interpretation. Cloudflare 4xx and 5xx responses remain native Cloudflare responses.

Only these provider response headers are forwarded when present:

• content-type
• content-encoding
• etag
• location
• retry-after
• ratelimit
• ratelimit-policy
• x-amzn-requestid
• x-amz-request-id
• x-request-id
• cf-ray

Gateman does not forward every Cloudflare response header. Redirects are disabled, and the caller must interpret Cloudflare response fields, pagination, validation errors, and provider rate limits.

Response-size and compression behaviour

The maximum provider response body is 4 MiB (4,194,304 bytes). Gateman's transport disables automatic decompression and enforces this limit while receiving the provider representation. Therefore compressed bytes count toward the transport ceiling; the limit is not a promise about the size of a decompressed document. content-encoding, when supplied by Cloudflare, is forwarded.

An oversized response is not returned partially. Gateman responds with HTTP 502 and a Gateman JSON error such as:

{
  "ok": false,
  "error": "Provider response exceeded Gateman transport limits"
}

Failure to return a response does not prove that Cloudflare did not receive or execute a mutation.

Credentials and Cloudflare authorization

The application-scoped encrypted provider credential is:

• CLOUDFLARE_API_TOKEN

Gateman retrieves it internally and sends it only as the provider bearer credential. It never returns the token through /cloudflare/request. This capability does not require secrets:read; generic application-secret retrieval is a separate authorization path.

Do not put the Cloudflare token in source, configuration committed to an application, prompts, logs, browser code, or client-visible request bodies. Cloudflare API-token permissions decide which accounts, zones, resources, and operations are available. Gateman does not broaden or replace them.

Request and response limits

These are Gateman transport limits, separate from Cloudflare API quotas, pagination limits, and resource-specific constraints. Streaming, redirects, multipart transfers, automatic pagination, and automatic retries are not part of this capability.

Operation accounting and concurrency

The billable operation is cloudflare.request. One invocation that passes authentication, validation, provider admission, and monthly allowance checks consumes one operation whether Cloudflare returns success, a native error, or execution becomes uncertain.

Authentication failures, invalid envelopes, request-size rejections, pre-admission concurrency rejections, provider-admission failures, and monthly allowance rejections do not consume an operation. Credential lookup, network, timeout, oversized-response, and Cloudflare 4xx/5xx failures occur after admission and consume the operation.

Gateman may reject temporary application or provider-bound admission with HTTP 429, normally with Retry-After. An unavailable admission or accounting dependency may return HTTP 503. Monthly allowance exhaustion returns HTTP 403 with monthly_operation_limit_reached. Internal slot capacities and reservation implementation details are not part of this public contract.

The signed X-GM-Idempotency-Key does not change these accounting rules. It does not create a replay record or prevent a second accepted provider request.

Error matrix

Gateman-generated errors commonly use { "ok": false, "error": "..." }. Native Cloudflare responses do not use that envelope, and Cloudflare's own error schema remains authoritative.

Provider execution uncertainty

A timeout, connection failure after transmission, or oversized response can return 502 even if Cloudflare received or executed the request. It is not a safe-to-retry signal by itself. Inspect resource state, use any Cloudflare-native idempotency or conditional request mechanism supported by the selected endpoint, and verify mutations after uncertain outcomes.

Gateman does not automatically retry, replay, paginate, or reconcile Cloudflare requests. If-Match and If-None-Match are available for conditional requests where the Cloudflare endpoint supports them; Gateman does not interpret their semantics.

Environment behaviour

This capability is environment-independent. Its manifest has no environment field, and the Official clients do not select a staging or development Cloudflare credential for this route. The effective Cloudflare account, zones, resources, and permissions are determined by the configured application token and Cloudflare's authorization model.

An environment label in an application does not make this route a simulator or test-mode endpoint. A permitted request reaches Cloudflare's real API and may mutate real Cloudflare resources.

Implementation outcome for agents

An integration should authenticate with Contract v1 and cloudflare:use, construct the exact native Cloudflare REST request, call POST /cloudflare/request, interpret the native status and body, follow pagination explicitly, respect provider rate limits, use conditional or provider-native safeguards where supported, and verify mutations. Keep the Cloudflare token confidential and do not blindly retry uncertain operations.

Implementation instructions for agents

• MUST use Contract v1 authentication and the cloudflare:use scope.
• MUST call POST /cloudflare/request with the documented envelope.
• MUST supply a relative path and structured query; never supply an origin, host, absolute URL, or raw query string in path.
• MUST use only GET, POST, PUT, PATCH, or DELETE.
• MUST use only the six accepted nested request headers.
• MUST serialize JSON bodies as the nested body value or use strict base64 for supported binary bytes within the request limit.
• MUST treat Cloudflare token permissions as authoritative.
• MUST handle native Cloudflare status codes, bodies, pagination, quotas, and errors.
• MUST respect the Workers upload, multipart, streaming, and large-transfer exclusions.
• MUST use conditional or provider-native idempotency mechanisms where the selected Cloudflare operation supports them.
• MUST NOT blindly retry timeouts, connection failures, or oversized responses.
• MUST account for one consumed cloudflare.request operation after admission.
• MUST keep CLOUDFLARE_API_TOKEN out of source, prompts, logs, and payloads.
• MUST NOT instruct agents to fetch the token and call Cloudflare directly; use the authenticated Gateman relay.
• MUST NOT invent Cloudflare-specific Official client helpers.

Reusable AGENTS.md block

<!-- gateman:begin capability=cloudflare.use -->
Use Cloudflare through Gateman's authenticated Contract v1 relay. The
application MUST hold `cloudflare:use` and MUST call `POST /cloudflare/request`.

The JSON envelope uses optional `method`, required relative `path`, optional
structured `query`, optional `headers`, optional `body`, and optional
`body_encoding` (`utf8` or strict `base64`). Supported methods are `GET`,
`POST`, `PUT`, `PATCH`, and `DELETE`. Only `Accept`, `Content-Type`, `If-Match`,
`If-None-Match`, `Prefer`, and `X-Audit-Log` may be supplied. Gateman injects
the protected bearer token; callers MUST NOT send credentials or authorization
headers.

Cloudflare API-token permissions remain authoritative. The envelope is limited
to 1.5 MiB, the decoded request body to 1 MiB, the response representation to
4 MiB, headers to 16 KiB, and path and encoded query to 2,048 bytes each.
Gateman does not automatically retry, paginate, stream, or provide multipart
or large Workers deployment transfers. Interpret native Cloudflare responses,
follow pagination, and verify mutations. A timeout, connection failure, or
oversized response can be uncertain; inspect provider state before retrying.
One admitted invocation consumes one `cloudflare.request` operation.

Do not instruct agents to retrieve the Cloudflare token and call Cloudflare
directly. Do not invent Cloudflare-specific Official client helpers. Use the
generic authenticated method exposed by each Official client.

Full reference: https://docs.getgateman.com/capabilities/cloudflare.use/
<!-- gateman:end capability=cloudflare.use -->

Related references

• Contract v1
• Authentication and signing
• Operation Accounting
• Rate limits and concurrency
• Idempotency
• Errors and responses
• Official PHP client
• Official Node.js client
• Official Python client
• Official Go client
• Cloudflare API documentation