|
| 1 | +## Configuration |
| 2 | + |
| 3 | +To use this provider, add an entry to `creds.json` with `TYPE` set to `VERCEL` |
| 4 | +along with a [Vercel API Token](https://vercel.com/account/settings/tokens) and your team ID. |
| 5 | + |
| 6 | +Example: |
| 7 | + |
| 8 | +{% code title="creds.json" %} |
| 9 | +```json |
| 10 | +{ |
| 11 | + "vercel": { |
| 12 | + "TYPE": "VERCEL", |
| 13 | + "team_id": "$VERCEL_TEAM_ID", |
| 14 | + "api_token": "$VERCEL_API_TOKEN" |
| 15 | + } |
| 16 | +} |
| 17 | +``` |
| 18 | +{% endcode %} |
| 19 | + |
| 20 | +**API Token** |
| 21 | + |
| 22 | +You can create a Vercel API Token via [Vercel Account Settngs](https://vercel.com/account/settings/tokens). |
| 23 | + |
| 24 | +**How to grab team ID** |
| 25 | + |
| 26 | +Log in to your Vercel account and navigate to `https://vercel.com`. Switch to your desired team with the Vercel team switcher if needed. |
| 27 | + |
| 28 | + |
| 29 | + |
| 30 | +Now you can find your team ID in your browser's address bar, copy the path (**without** any leading `/` or trailing `/`) and paste it into your `creds.json` file. |
| 31 | + |
| 32 | + |
| 33 | + |
| 34 | +If you are familiar with the Vercel API, you can also grab your team ID via Vercel's [Teams - List all teams API](https://vercel.com/docs/rest-api/reference/endpoints/teams/list-all-teams). In response's `id` field you will able to see a string starts with `team_`, and in response's `slug` field you will able to see a string consists of a slugified version of your team name. Both `id` and `slug` can be used as `team_id` for your `creds.json`. |
| 35 | + |
| 36 | +**Legacy Vercel Account Domains** |
| 37 | + |
| 38 | +If you are an early Vercel user (when Vercel didn't implement teams back then), the domains you added back then might not be migrated to your personal team. You will be able to find and manage those domains in Vercel's [Account Settings - Overview - Domains](https://vercel.com/account/domains). |
| 39 | + |
| 40 | +In this case, you should use an empty string as the team ID: |
| 41 | + |
| 42 | +{% code title="creds.json" %} |
| 43 | +```json |
| 44 | +{ |
| 45 | + "vercel": { |
| 46 | + "TYPE": "VERCEL", |
| 47 | + "team_id": "" |
| 48 | + } |
| 49 | +} |
| 50 | +``` |
| 51 | +{% endcode %} |
| 52 | + |
| 53 | +It is also possible to manually migrate your domains from your Vercel account to your personal team via the link mentioned above. Whether you choose to migrate your domains or not is up to you, this provider supports both cases. |
| 54 | + |
| 55 | +## Usage |
| 56 | + |
| 57 | +An example configuration: |
| 58 | + |
| 59 | +{% code title="dnsconfig.js" %} |
| 60 | +```javascript |
| 61 | +var REG_NONE = NewRegistrar("none"); |
| 62 | +var DSP_VERCEL = NewDnsProvider("vercel"); |
| 63 | + |
| 64 | +D("example.com", REG_NONE, DnsProvider(DSP_VERCEL), |
| 65 | + A("test", "1.2.3.4"), |
| 66 | +); |
| 67 | +``` |
| 68 | +{% endcode %} |
| 69 | + |
| 70 | +## Caveats |
| 71 | + |
| 72 | +### New domains |
| 73 | + |
| 74 | +We do not support adding a domain to Vercel via `dnscontrol push`, as Vercel now requires a domain be associated with a project before it can utilize Vercel's DNS. You should use Vercel's [DNS Dashboard](https://vercel.com/dashboard/domains) to add a domain. |
| 75 | + |
| 76 | +### System-managed Records |
| 77 | + |
| 78 | +Vercel will create "system-managed records" for you when you add a domain to Vercel. Those records can not be deleted or modified. |
| 79 | + |
| 80 | +You can add your own records and Vercel will prefer your created records over their system-managed records, but the system-managed records will always be present even if you add your own "override" records. |
| 81 | + |
| 82 | +As of November 2025, the known system-managed records are: |
| 83 | + |
| 84 | +- `CAA 0 issue "letsencrypt.org"` |
| 85 | + - Vercel uses Let's Encrypt to issue certificates for your project deployed on Vercel, thus Vercel automatically creates a CAA record to ensure Let's Encrypt can issue certificates, but you can always add your own CAA records. |
| 86 | +- `CNAME cname.vercel-dns.com.` |
| 87 | + - Vercel uses a CNAME record to point your deployed project to their infrastructure, but you can always add your own CNAME records (which allows you to put a third-party CDN in front of Vercel's infrastructure). |
| 88 | + |
| 89 | +In Vercel's API, those system-managed records will have their `creator` set to `system`. We use this to identify and ignore system-managed records, to prevent DNSControl from interfering with them. You won't see them in `dnscontrol diff` or `dnscontrol preview`. |
| 90 | + |
| 91 | +### Comment |
| 92 | + |
| 93 | +This provider does not recognize Vercel DNS record comment. And we encourage you not to use it. You should use JavaScript comment in your `dnsconfig.js` instead. |
| 94 | + |
| 95 | +In the future, we might use the comment field to store additional metadata for other purposes. |
| 96 | + |
| 97 | +### CAA |
| 98 | + |
| 99 | +As of November 2025, Vercel has a bug that does not accept CAA records with any extra fields that are not `cansigncansignhttpexchanges`: |
| 100 | + |
| 101 | +``` |
| 102 | +# OK |
| 103 | +CAA 0 issue "letsencrypt.org" |
| 104 | +CAA 0 issuewild "letsencrypt.org" |
| 105 | +CAA 0 issue "digicert.com; cansignhttpexchanges=yes" |
| 106 | +
|
| 107 | +# Panic |
| 108 | +CAA 0 issue "letsencrypt.org; validationmethods=dns-01" |
| 109 | +CAA 0 issue "letsencrypt.org; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234" |
| 110 | +``` |
| 111 | + |
| 112 | +This is most likely a bug on Vercel's side where Vercel misinterprets other fields as `cansignhttpexchanges`, as the API error response implies: |
| 113 | + |
| 114 | +``` |
| 115 | +invalid_value - Unexpected "cansignhttpexchanges" value. |
| 116 | +``` |
| 117 | + |
| 118 | +### Rate Limiting |
| 119 | + |
| 120 | +Vercel is rate limiting requests somewhat heavily. Some of the rate limit and remaining quota is advertised in the API response headers (`x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset`), some of HTTP 429 contains the `retry-after` response header, some of the rate limit rules can be found in [Vercel's API documentation](https://vercel.com/docs/limits#rate-limits). |
| 121 | + |
| 122 | +So far, the known rate limit rules are: |
| 123 | + |
| 124 | +- create up to 100 dns records per hour (3600 seconds) |
| 125 | +- update up to 50 dns records per minutes (60 seconds) |
| 126 | + |
| 127 | +The rate limit rules for the following actions are unknown: |
| 128 | + |
| 129 | +- list dns records - we assume 50 page per minute (60 seconds) |
| 130 | +- delete dns records - we assume 50 dns records per minute (60 seconds) |
| 131 | + |
| 132 | +All operations do not share rate limit quota, each operation has its own rate limit quota. |
| 133 | + |
| 134 | +We will burst through half of the quota, and then it spreads the requests evenly throughout the remaining window. This allows you to move fast and be able to revert accidental changes to the DNS config in a somewhat timely manner. We will retry rate-limited requests (status 429) and respect the advertised `Retry-After` delay. |
| 135 | + |
| 136 | +If you are mass migrating your DNS records from another provider to Vercel, we recommended to upload a BIND zone file via [Vercel's DNS Dashboard](https://vercel.com/dashboard/domains). You can use DNSControl to manage your DNS records afterwards. |
| 137 | + |
| 138 | +### Change Record Type |
| 139 | + |
| 140 | +Vercel does not allow the record type to be changed after creation. If you try to update a record with a different type (e.g. changing `A` to `CNAME/ALIAS`), we will delete the old record and create a new one. This will count as two separate requests, which may exceed the rate limit. Also be careful about the downtime caused by the deletion and creation of records. |
| 141 | + |
| 142 | +### Minimum TTL |
| 143 | + |
| 144 | +Vercel enforces a minimum TTL of 60 seconds (1 minute) for all records. We will always override the TTL to 60 seconds if you try to set a lower TTL. |
0 commit comments