# Connect Cloudflare DNS

An account of Cloudflare DNS is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. DNS zones and records on Cloudflare : records, BIND import / export, zone settings, DNSSEC and cache purge — one resource per zone.

One account is one Cloudflare API token; one resource is one DNS zone (a domain). A mission touches only the zones it was given. DNS has no environment: ordinary records, apex / MX / NS changes, deletions, imports and zone settings are separate permissions instead.

Permissions, presets and tools of this service: [Cloudflare DNS plugin](/plugins/cloudflare-dns).

## How to connect

On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (`providers.<id>.*`, see [configuration keys](/docs/configuration/keys)). Every instance registers its own app: this gateway never uses an app shared with another one.

### The usual way: with a key pasted by hand

Where: [https://dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens)

What the connect page asks:

- API token (secret): Create a token scoped to the zones the agent may touch, with Zone:Read, DNS:Edit and, as needed, Zone Settings:Edit, Cache Purge:Purge and Zone:Edit (zone deletion). Never a Global API Key.

## Disconnecting

Delete the API token in the Cloudflare dashboard, under My Profile, API Tokens.

## Registration notes from the plugin

From the plugin's [README](https://github.com/vaubaan/gateway/blob/main/plugins/cloudflare-dns/README.md), written for the people who register the app or create the token.

### Credential and resources

Kind `api-key`, one required secret field:

| Field       | Pattern                | Purpose                                                             |
| ----------- | ---------------------- | ------------------------------------------------------------------- |
| `api_token` | `^[A-Za-z0-9_-]{20,}$` | A Cloudflare API token. A Global API Key (`email\|key`) is refused. |

There is no company-registered app for Cloudflare DNS: the owner creates the
token at `https://dash.cloudflare.com/profile/api-tokens` and pastes it.
Scope it to the zones the agent may touch, with **Zone:Read** and
**DNS:Edit**, plus **Zone Settings:Edit**, **Cache Purge:Purge** and
**Zone:Edit** only when the corresponding tools are wanted.

`discoverResources` pages through `GET /zones` (50 per page, at most 500
zones, no account filter) and returns **one resource per zone**:

```ts
{ provider: 'cloudflare-dns', ref: '023e105f4ecef8ad9ca31a8372d0c353', displayName: 'example.com',
  metadata: { zone_name: 'example.com', account_id: '01a7362d577a6c3019a474fd6f485823',
              account_name: 'Example Corp', status: 'active' } }
```

The `ref` is the zone id every tool takes as `zone_id`. `account_id` becomes
the `account[…]` segment of the slices; `zone_name` lets the classifier tell
an apex record from a subdomain record.