Provider guides
Cloudflare Domains: configuration and operations
Check availability, register domains through Cloudflare Registrar and manage DNS zones and records through the Cloudflare API.
On this page
Status and workflow
The Cloudflare Domains extension connects the Domains Module to Cloudflare in two roles. cloudflare-registrar checks availability and registers domains through the Cloudflare Registrar API. cloudflare-dns prepares zones and manages DNS records through the Cloudflare DNS API. Both roles use the same account ID and API token, and every call goes to https://api.cloudflare.com/client/v4.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the Cloudflare Registrar, DNS and Zones APIs and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own Cloudflare account remains an operator responsibility: register one low-cost domain and change one DNS record on your own Cloudflare account before you sell domains. Operations under Not supported are not advertised.
Requirements
- Agovena Core
^0.0.1. - The Domains Module, enabled before this extension.
- A Cloudflare account with a billing profile that has a valid default payment method, and a default registrant address book entry with the accepted agreement. Registration uses express mode and sends no contact data.
- An API token with Registrar permissions for registration and
Zone EditorDNS Editfor zones and records.
Set up the package
- Enable the Domains Module, then open Admin > Extensions and enable Cloudflare Domains.
- In the Cloudflare dashboard, copy the account ID and create an API token with the permissions listed above.
- Complete the billing profile and the default registrant entry in the Cloudflare dashboard. Agovena cannot set them for you.
- Save
account_idandapi_token. The token is stored as a secret and is never redisplayed. - Use
cloudflare-registrarfor registration andcloudflare-dnsfor DNS in the Domains Module.
Supported operations
| Operation | Behaviour |
|---|---|
| Availability | POST /accounts/{account_id}/registrar/domain-check. A domain is available only when Cloudflare reports registrable: true and the tier is not premium. The price comes from pricing.registration_cost. |
| Registration | Reads the existing registration workflow, runs a real-time availability check and then sends POST /accounts/{account_id}/registrar/registrations with domain_name and auto_renew. |
| Status refresh | The Domains Module runs agovena:refresh-domain-registrations every five minutes. It only reads registration-status and never submits a second registration. |
| Zone preparation | Reuses a zone in the account only on an exact name match, otherwise creates a full zone. |
| DNS records | List, create, update and delete A, AAAA, CNAME, MX, NS and TXT records. Names are expanded to full names inside the zone, MX needs a priority from 0 to 65535 and proxied is only sent for A, AAAA and CNAME. |
Workflow states pending, in_progress, blocked and action_required keep the registration in registering. succeeded becomes active with the expiry date from Cloudflare and prepares the DNS zone. failed becomes failed with the Cloudflare error code and message in the registration meta. For action_required, the meta keeps context.action so you can complete the step in the Cloudflare dashboard.
auto_renew: true authorizes Cloudflare to charge the default payment method of the account for renewals up to 30 days before expiry. That charge happens outside Agovena billing.
Not supported
- Renewal. The Registrar API has no renewal endpoint, so
renewalis not advertised and a renew request fails with an explicit not-supported error. - Transfers, nameserver changes, contact updates, premium registrations and multi-year terms.
- SRV, CAA and other record types that use structured data.
- A health check callback.
Failure handling and ownership
- Cloudflare allows one registration per domain. An existing
pending,in_progress,blocked,action_requiredorsucceededworkflow is returned as is, so registering again acts as a status refresh and never sends a second billable request.action_requiredis never resubmitted. - Unavailable and premium domains are refused before any billable request.
- When the registration request fails through a timeout, transport error or rejection, the workflow status is read once. A newly started workflow is reported instead of the error. Otherwise the record becomes
failed, and a later attempt reads the workflow first, so it resumes instead of paying twice. - Responses without a documented
state, with an inconsistentcompletedflag or for another domain are rejected. A failed status lookup leaves the registration unchanged for the next run. - DNS records that Cloudflare refuses show a form error instead of breaking the request.
- All HTTP calls are refused in the
demoenvironment, redirects are never followed and error messages never include the API token.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
account_id |
string |
No | No | Empty |
api_token |
string |
No | Yes | Empty |
Both fields are optional in the manifest, but registration and DNS changes need both. The token must carry the permissions listed under Requirements. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.