---
title: Provider APIs
description: Reference for the provider contract and bundled Cloudflare and Vercel adapters.
sidebar:
  label: Provider APIs
seo:
  title: DomainKit provider API reference
---

## Provider contract

`DnsProvider.Interface` is the capability required by planning, application, deletion, and
provider-backed verification.

| Member         | Purpose                                                                         |
| -------------- | ------------------------------------------------------------------------------- |
| `id`           | Stable provider identity embedded in plans and checked before apply.            |
| `listRecords`  | Read all records in an authoritative zone, including opaque records.            |
| `getRecord`    | Read one record by provider record ID.                                          |
| `createRecord` | Create a normalized DomainKit record and return its provider ID when available. |
| `deleteRecord` | Delete a record by the ID captured in an application receipt.                   |

Provider failures use `DnsProvider.Error` with operation, provider ID, optional status/code,
normalized reason, and optional retry delay. Preserve the original cause for diagnostics, but do not
send secrets or raw provider responses to the browser.

Promise-first adapters can implement `DnsProvider.AsyncInterface` and use `fromAsync` or
`layerFromAsync`. `toAsync` adapts an environment-free Effect provider in the opposite direction.

## Bundled providers

`Cloudflare` and `Vercel` each group:

- OAuth or Integration authorization helpers;
- token-based constructors;
- account or team discovery;
- zone discovery; and
- a `DnsProvider` implementation.

The provider namespaces do not persist OAuth state, credentials, connections, plans, or receipts.
Your host owns those stores and reconstructs a provider service for each authorized operation.

### Cloudflare

`Cloudflare` supports OAuth and API-token authentication, account discovery from an authorized
zone, zone discovery, and provider reconstruction from a stored non-secret account context plus a
host-held credential.

### Vercel

`Vercel` supports Integration authorization and token authentication, personal or team context,
zone discovery, and provider reconstruction from the stored context plus a host-held credential.

## Opaque records

An adapter must return unsupported provider records as `DnsRecord.Opaque` values rather than
dropping them. Planning preserves opaque records and refuses unsafe assumptions about data it cannot
model. Deletion targets only provider record IDs captured by a DomainKit receipt.

## Acceptance

Run the public `ProviderConformance` suite against a fresh isolated instance, then add adapter tests
for authentication, discovery, pagination, provider error bodies, rate limits, and live API behavior.

Continue with [Implement a DNS provider](/docs/guides/implement-provider),
[Cloudflare](/docs/providers/cloudflare), or [Vercel](/docs/providers/vercel).