APIZ guide

Cloudflare Adapter

Use the Cloudflare Adapter for Cloudflare v4 account, zone, DNS-record, and other endpoint operations. It gives Policy semantic Cloudflare actions while the upstream API token remains inside APIZ.

What This Adapter Supports

Official v4 API base URL by default.
Bearer API-token authentication.
Account, zone, DNS-record, and fallback endpoint resources.
Generated APIZ bearer credentials for Cloudflare SDKs or HTTP clients.
Path or domain routing, semantic connection tests, and a read-only template.

Credential Boundary

The API Instance stores the Cloudflare API token as write-only credential material. The agent receives a generated APIZ bearer credential, normally with a cf_apiz_ prefix. APIZ validates that credential, evaluates Policy, removes caller authentication, and injects the Cloudflare token only for an allowed upstream request.

allowed_account_ids and allowed_zone_ids make intended scope reviewable but do not enforce it without Policy. Provider-side token restrictions remain the first boundary.

Prepare The Upstream Credential

Create a scoped Cloudflare API token, not a Global API Key. Restrict it to:

the exact account or zones APIZ needs;
read permissions unless the agent has an explicit write requirement; and
only the Cloudflare products needed for the task.

Keep the account and zone IDs available for connection tests and Policy resources. Do not copy the token into tags, Policy source, or test parameters.

Web Console

Open API Instances → Create API Instance → Cloudflare.
Enter a name and the token only under API token.
Add optional account and zone IDs under Account and zone hints.
Choose a connection-test preset. Start with Verify token or a read-only listing operation.
Attach Allow Cloudflare reads when read-only enforcement is required.
Test the connection, review the redacted result, and save.

The official endpoint is already configured. Change it only for controlled testing of a compatible endpoint.

CLI

apiz adapter explain cloudflare

read -rsp "Cloudflare API token: " CLOUDFLARE_TOKEN && printf '\n'
printf '%s' "$CLOUDFLARE_TOKEN" | jq -Rs '{credential: .}' |
apiz -o json api create \
  --adapter cloudflare \
  --name production-dns \
  --config-json '{"allowed_zone_ids":["zone-example"]}' \
  --test-config-json '{"preset":"list_dns_records","parameters":{"zone_id":"zone-example"}}' \
  --credential-stdin
unset CLOUDFLARE_TOKEN

Use a real zone ID in local execution. The synthetic identifier above is not a working Cloudflare resource.

Give An Agent Access

apiz -o json client create --name dns-agent
apiz client bind <client-id> --api-instance <api-instance-id> --alias cloudflare
apiz client credentials create <client-id> --binding cloudflare --ttl 1h --format curl

In the Web Console, perform the same steps under Clients → Add Binding → Create Temporary Credentials. Select only the Cloudflare Binding and the shortest practical TTL.

Use It From The Agent

Verify the APIZ-issued credential or list zones through the generated endpoint:

curl -fsS \
  -H "Authorization: Bearer $APIZ_TEMPORARY_CREDENTIAL" \
  "$APIZ_CLOUDFLARE_ENDPOINT/zones"

Cloudflare SDKs that accept a custom base URL and bearer token can use the endpoint and credential from the Setup Manifest. Never configure the SDK with the upstream Cloudflare token inside the agent runtime.

Policy Actions And Resources

Resource	Read	Write	Dangerous
Account	`cloudflare:account:read`	`cloudflare:account:write`	`cloudflare:account:delete`
Zone	`cloudflare:zone:read`	`cloudflare:zone:write`	`cloudflare:zone:delete`
DNS record	`cloudflare:dns_record:read`	`cloudflare:dns_record:write`	`cloudflare:dns_record:delete`
Other v4 endpoint	`cloudflare:endpoint:read`	`cloudflare:endpoint:write`	included in fallback write risk

The Allow Cloudflare reads template allows the three semantic read actions and the fallback read action, then denies everything else. Add account or zone resource conditions when one token covers more than the agent should reach.

Connection Tests

Preset	Required parameters	Behavior
`verify_token`	none	`GET /user/tokens/verify`
`list_accounts`	none	Lists visible accounts
`get_account_info`	`account_id`	Reads one account
`list_zones`	none	Lists visible zones
`get_zone_info`	`zone_id`	Reads one zone
`list_dns_records`	`zone_id`	Lists DNS records for one zone

All presets are read-only. An advanced one-off path is available for troubleshooting, but should not replace a repeatable semantic preset.

Evidence And Troubleshooting

cloudflare_connection_unauthorized: confirm token validity and provider permissions, then rotate the stored API Instance credential.
Missing account or zone parameter: supply it under the preset's parameters; do not put the token there.
Policy denies a DNS update: inspect the normalized DNS-record action and zone resource before broadening the rule.
Cloudflare returns an error after APIZ allows: the upstream was reached; inspect the redacted response status and provider error code.

Follow request evidence for the complete decision and upstream timeline.

Current Limitations

Unknown Cloudflare endpoints fall back to coarse endpoint read/write actions rather than receiving invented resource semantics.
Account and zone hints do not enforce authorization by themselves.
OAuth token acquisition and rotation are not managed by this adapter; rotate a replacement token through the API Instance workflow.