# DNS providers

URL: https://docs.vaultpanel.net/guides/dns-and-email/dns-providers

> Connect a Cloudflare or Namecheap account so websites whose DNS stays there can get Let's Encrypt wildcard certificates through the provider's API.

A wildcard certificate (`*.example.com`) is checked by Let's Encrypt through DNS: a `TXT` record has to appear in the domain's DNS while the certificate is issued and at every renewal. When the domain's DNS is at Cloudflare or Namecheap, VaultPanel's agent can add that record through the provider's API, so you get wildcard certificates without moving the domain's DNS to one of your servers.

DNS providers are used only for this. They do not manage your other records.

## Supported providers

| Provider | Credentials | Where to get them |
| --- | --- | --- |
| **Cloudflare** | **API token** | A token with the **Zone > DNS > Edit** permission for your domains: in Cloudflare, **My Profile > API Tokens > Create Token > Edit zone DNS**. |
| **Namecheap** | **API user** and **API key** | Your Namecheap user name, and the key from **Profile > Tools > Namecheap API Access**. |

> **Before you use Namecheap:**
Namecheap turns its API on only for accounts with 20 domains, or $50 on the account or spent in the last two years, and answers only the IPv4 addresses you whitelist there. Whitelist the public IPv4 address of each server that issues certificates. Namecheap's API also replaces all of a domain's records at once, so VaultPanel writes back every record exactly as it read it, and changes nothing when it cannot read them all.

## Add a provider

### Open the DNS providers card

Go to **Web > DNS Zones** and find the **DNS providers** card. Click **Add provider**.

### Enter the account

| Field | Notes |
| --- | --- |
| **Provider** | **Cloudflare** or **Namecheap**. Cannot be changed later. |
| **Name** | How it shows when you issue a certificate, such as `Cloudflare (main account)`. Up to 60 characters. |
| **API user** | Namecheap only. |
| **API token** / **API key** | The secret. |

### Save it

Click **Add provider**. You can add several accounts of the same provider.

The secret is stored encrypted in the panel and never shown again. When you edit a provider, leave the secret empty to keep the saved one.

## Issue a wildcard certificate through a provider

1. Make sure the domain uses the provider's name servers.
2. Open the website, go to its **SSL** tab, tick **Wildcard certificate** and choose the account in **Check DNS through**.
3. Issue the certificate.

The certificate's renewals go through the same provider. See [SSL certificates](https://docs.vaultpanel.net/guides/websites/ssl-certificates#wildcard-certificates) for the rest of the options.

## How the credentials are used

- The secret is sent to the server's agent only inside the job that issues the certificate, and is removed from the stored job once it ends.
- The agent keeps a copy that only root can read, so Certbot can renew the certificate. It stays until a certificate on that website is issued again another way, or the website is deleted.
- For Namecheap, the agent changes the records of the domain as registered (such as `example.com` for `shop.example.com`), calling from the server's public IPv4 address.

## Edit and remove providers

The **DNS providers** card lists each account with the number of certificates that renew through it.

- **Edit** changes the name, user or secret. Servers keep the secret they already have until a certificate there is issued again.
- **Remove** is refused while certificates renew through the provider. Issue them again another way, or turn HTTPS off on those websites, first.

## Requirements

- Agent 0.38.0 or newer on the website's server.
- Only staff can add, see or use DNS providers: `dns.read` to use one when issuing a certificate, `dns.manage` to add, change or remove them. Hosting customers cannot use them.
