FastCF

Async Python access to the Cloudflare API

fastcflare provides an async Cloudflare API client built from Cloudflare’s OpenAPI schema. Use CloudflareApi to browse API operations, manage zones and DNS records, and create scoped tokens. The examples below show user-token access and account-owned tokens.

from fastcore.utils import *
from fastcflare import *

Quickstart

from fastcflare import *

usrtok = os.environ['CLOUDFLARE_USR_TOK']

ucf = CloudflareApi(token=usrtok)
(await ucf.verify()).result.status

'active'

(await ucf.zones.list()).result[0].name

'aaa.as'

Create a token

Create a token with Zone Read and DNS Write permissions for one domain. Replace xxx with the domain name. The client used to create it must have permission to create tokens:

doms = ['xxx']
pnms = ('Zone Read', 'DNS Write')
tok = await ucf.create_token(doms, pnms, 'domain mgt')
dns_token = tok.result.value

Store the token securely. For APIs that accept a Global API Key, construct the client with CloudflareApi(email=os.environ['CLOUDFLARE_EML_ADD'], api_key=os.environ['CLOUDFLARE_API_KEY']) instead.

Use the new token to list DNS records, create a test A record, and delete that record. This changes DNS records in an existing zone; it does not create or delete the domain:

domnm = 'xxx'
zones = (await ucf.zones.list(name=domnm)).result
zid_sp = zones[0].id

dcf = CloudflareApi(token=dns_token)
print((await dcf.zones.dns_records.list(zone_id=zid_sp)).result[:3])
rec = await dcf.zones.dns_records.post(zid_sp, type='A', name='test-delete-me.xxx', content='192.0.2.1', ttl=1)
print(rec.result.id, rec.result.name)
print((await dcf.zones.dns_records.delete(zid_sp, rec.result.id)).result.id)

Intro to Account Tokens

Account-owned API tokens belong to an account and act as service principals with their own permissions. They support CI/CD and service integrations that need to keep working after the creating user leaves the organization. The API endpoint is /accounts/{id}/tokens.

Creating Account Tokens

Cloudflare requires Super Administrator permission to create or update account-owned tokens. The creation endpoint accepts an API token with Account API Tokens Write. The following example uses the official Cloudflare Python SDK with token authentication:

from cloudflare import Cloudflare
cf = Cloudflare(api_token=your_cf_token)
accts = cf.accounts.list()
acct_id = next(iter(accts)).id

Look up permission groups available to the account:

groups = list(cf.accounts.tokens.permission_groups.list(account_id=acct_id))
{g.name: g.id for g in groups if 'dns' in g.name.lower() or 'zone' in g.name.lower()}

For account-owned tokens, nest zone resources under the account resource. This example grants Zone Read and DNS Write across its zones:

tok = cf.accounts.tokens.create(account_id=acct_id, name="dns-all-zones", policies=[{
    "effect": "allow",
    "resources": {f"com.cloudflare.api.account.{acct_id}": {"com.cloudflare.api.account.zone.*": "*"}},
    "permission_groups": [{"id": g.id} for g in groups if g.name in ('Zone Read', 'DNS Write')]
}])
dns_tok = tok.value  # Store securely; the value is only returned at creation

A zone resource without the enclosing account, such as {"com.cloudflare.api.account.zone.*": "*"}, fails with: “Must specify a zone for account owned tokens, or nest zone under specific account resource”. Keep the nested format even when granting access to all zones.

Development

The op surface comes from cf_spec.py, Cloudflare’s OpenAPI schema in fastspec’s compact form. Refresh it from Cloudflare’s published schema with tools/build.py, then review the diff: op names can shift when the schema changes.