Provider accounts
Connect a DNS provider account once for many domains.
A provider account is a key for a DNS provider or registrar that the workspace connects once. CustomDomain™ checks the key before keeping anything, keeps it encrypted, and never returns it.
Where an account's key comes from
An account holds a key that reached the workspace in one of three ways, which are three of the six ways to connect:
- An API key you paste, through
POST /v1/provider-accountsor the console's Remember this key box. See Provider setup. - A provider sign-in that is kept, where the deployment keeps that provider's sign-in. The hosted service does at some providers (see Managed sign-ins). These are listed with the accounts, grouped by provider. On Connected accounts you can also add an account by signing in to the provider directly.
- A secure sign-in, at a provider that offers no sign-in a third party can use. After your customer signs in, our software makes a lasting API key. See Keys made at a secure sign-in, and GoDaddy and Namecheap for two of them.
One-click setup and adding the records by hand leave no account, since there is no key to keep.
We check the key by listing the provider's domains.
A provider that cannot list them is asked for one of the selected domains instead.
With scope all, name a domain the key manages in check_domain, or the call answers 400 check_domain_required.
A key is never kept unchecked.
Access
- Continuous: kept until you revoke it.
It keeps the records it wrote.
It puts back records that disappear, where the deployment has automatic repair on (monitoring).
It removes records when a domain is removed.
It re-applies them when you ask (
POST /v1/connections/{id}:reapply, which answersvia: "provider_account"). Whoever may manage the account also uses it to list the domains it reaches and connect more of them. A nameserver move may use it too. Each of these is in the audit log. - One time: used to connect the domains you choose, then deleted.
It works for an hour at most.
Past the hour, every use is refused with
409and the key is deleted, whether or not the hourly cleanup got to it first. The account stays as the record of what it connected.
Certificates renew without any DNS access, so both behave the same there.
Credentials that are used once
Some providers' credentials are never kept.
They are an account login, or a token that expires within hours or cannot be limited.
These are ALL-INKL (the KAS login) and Arsys (the Panel de Control password).
Azure DNS and Google Cloud DNS use access tokens that expire within an hour.
Binary Lane uses a token that reaches the whole account.
INWX, Loopia, Plesk and Subreg use logins, and Openprovider uses a token that expires after 48 hours.
They get one time access only.
"access": "continuous" answers 422 use_once_credential when you connect the account, switch its access or give it a new key.
A connect that names no access gets one time access.
The console offers them one time access only, and says why.
Sign-ins get the same choice: oauth:start takes "access": "continuous" or "one_time".
Continuous is offered where the deployment can keep that provider's sign-in.
Defaults and limits
When you leave them out, access is continuous, or one_time for a credential that is used once.
scope is selected if you send domains, and all if you do not.
POST /v1/provider-accounts/{id}/connect takes at most 200 domains per call, and answers 400 beyond that.
See connect many domains at once.
Checks at the provider have an hourly limit
Some calls ask a provider what a key reaches, using the key you saved.
One lists the domains a key reaches (POST /v1/provider-accounts/{id}/zones).
Another reads each new domain's zone when you widen a key made at a secure sign-in (PATCH /v1/provider-accounts/{id}, or a domain outside its scope in connect).
The others are Check now, and the reads that find which saved key can act for a domain.
They share one budget for the workspace: 60 reads an hour.
Each workspace's budget is its own, so another workspace cannot use it up.
- An answer CustomDomain™ kept from a read in the last ten minutes costs nothing. A call refused before it reached the provider (not allowed, no key) costs nothing either.
- When the budget is spent, those calls answer
429reach_quotawithRetry-After. That header gives the seconds until the hour ends, when the count starts again. Nothing was read at the provider, nothing changed, and nothing was spent from the hour. A call that needs several reads, such as a change naming ten new domains, takes them all or none. When they do not all fit, it is refused whole instead of checking some of them. The reads that were left stay for a smaller call.
{ "code": "reach_quota", "title": "Too many checks at DNS providers this hour.", "details": "this workspace has made as many checks of its keys at DNS providers as it may in an hour; nothing was changed, try again in about 40 minutes" }- Finding saved keys for a domain never fails for it.
Once the budget is spent, the saved access list offers the keys it can show without a read.
Those are the keys that already cover the domain and the answers it kept, so it offers fewer.
The next hour it reads the rest.
A shorter list does not mean a key cannot act.
Using a key by name (
POST /v1/connections/{id}:use-saved-access) that was not read because the budget was spent answers429reach_quota. It writes nothing, and does not answer409saved_access_not_usable. Wait forRetry-Afterand send it again. - The daily health check is outside the budget. It is not counted and never refused for it. So checks you run by hand cannot keep a key from being checked, and the daily check does not use up your hour.
Scope
All of the account's domains, including ones added later ("scope": "all").
Or a selected list ("scope": "selected", domains), picked from the provider's own list where it has one.
What each kind of account allows
How far an account's scope can be widened depends on how its key was made
(made_by.how), and the server enforces it:
| Kind | Widening its domains or scope |
|---|---|
Pasted (pasted): you made the key and pasted it | Any scope and any domains. Nothing is read at the provider; connecting a domain the key cannot write is what finds it. |
Made at a secure sign-in in the console (console_sign_in) | Only to domains the key reaches. Each domain you add is read with the key before anything is stored. A domain it does not reach is refused, and nothing is stored. all needs the provider to list the key's domains. |
Made at your customer's own sign-in (widget_sign_in) | Never widened, by anyone (403). It can be renamed, narrowed or removed. |
Narrowing and renaming ask the provider nothing, for every kind, with one exception.
A key made at a secure sign-in that goes from all back to selected reads each domain it names that the account does not already hold.
It reads at most 20 a call, and answers 400 too_many_domains_to_check beyond that, as explained below.
For a key made at a secure sign-in, PATCH /v1/provider-accounts/{id} reads each domain it adds, by its zone, with the key.
A call that names a domain the key does not reach answers 422 zone_not_reached, with those domains in domains.
It stores none of the call's domains, not even the ones that were reached:
{ "code": "zone_not_reached", "title": "This key does not reach every domain you added.", "domains": ["other.example"] }At most 20 new domains are read in a call, and the call answers 400 too_many_domains_to_check beyond that.
A failure that says nothing about the key, such as a timeout or a server error at the provider, answers 503.
It stores nothing, so try again.
An account that no longer holds its key answers 409, so renew it first.
Setting scope to all has no domain to read.
So it needs the provider to list the domains a key reaches, and the key to list them now.
A provider that cannot answers 422 scope_all_needs_list, so add the domains one at a time instead.
A key the provider refuses answers 422 ProviderAuthenticationError.
The scope all is no way round the read of a domain.
While a key made at a sign-in is on all, a domain you name that the account does not already hold is read with the key too.
That holds whether the call keeps all or goes back to selected.
The change is written on the account as it is after the reads, so a renewal that landed meanwhile is kept.
An account that lost its key meanwhile answers 409, and nothing is written.
Connect many domains at once
POST /v1/provider-accounts/{id}/connect connects up to 200 domains with the account's key in one call. Each entry
in domains is a name, or an object that puts that one domain into an application of its own:
{
"application_id": "app_web",
"domains": [
"www.example.com",
{ "domain": "shop.example.com", "application_id": "app_store" },
"docs.example.com"
]
}A domain goes into the first of these that names an application:
- the application named for that domain;
- the call's
application_id, which you can leave out; - The application that already holds the domain in your workspace (its connection's own). So a domain you already serve links to the account where it lives, and is not connected a second time.
A domain none of those names answers 400, and so does one that two applications hold or that the call names for two
different applications. A name written twice is one domain, and the 200 counts domains, not entries.
Everything below is checked before the first record is written, so a call that is refused changes nothing:
- The caller may manage the account. An admin, an owner or the member who connected it. Anyone else gets
403before the body is read, so a member cannot use or widen a key they may not manage. - The key serves every application the call uses.
A key made at a secure sign-in serves its own application and the ones an admin shared it with (
application_ids). Any other application answers403("this key is not shared with this application; an admin or an owner can share it"). An application that is not your workspace's answers404. - Every domain is inside the account's scope.
A domain outside it answers
400and names the domains. A key made at a secure sign-in in the console is the one exception. A zone is the part of a domain your DNS provider holds, such asexample.comforshop.example.com. When a read of the domain's zone works with that key, the domain connects with no new sign-in. The zone joins the scope once a write there works. A zone the key does not reach answers422zone_not_reached, with those domains indomains. A provider that cannot answer (a timeout or a server error) answers503, never a refusal of the key. Both are the answersPATCHgives, and nothing is written. A call reads at most 20 such zones, once each, and answers400too_many_domains_to_checkbeyond that. To widen the scope on its own, usePATCH /v1/provider-accounts/{id}.
Each result in results names the application_id the domain went into, with its status: connected, already or failed.
A domain whose write fails does not stop the others.
A call that connected at least one domain makes one provider_account.domains_connected row in the audit log.
The row names those domains and no others.
A domain already serving and already linked to this account is left as it is (already).
A call that only names such domains leaves no row.
See the API reference.
More domains in the account
An account's key often reaches more domains at the provider than your workspace has connected.
For whoever manages the account, two answers carry more_domains.
They are GET /v1/provider-accounts/{id} and the answer of a secure sign-in's keep.
more_domains is the domains the key lists, minus the ones your workspace has connected.
A console can ask "This IONOS account holds 11 more domains. Connect them?" and send the list to the connect call above.
- A domain counts as connected when your workspace has a connection for it, or for a name under it, in any application. A failed connection and a test mode one count for nothing.
- The list is sorted. It is empty for a provider that cannot list the domains of a key (see which providers list their domains).
- It can include domains outside the account's scope, such as a key made for one domain that reaches the whole account at the provider. The connect call refuses those until the scope covers them.
- Listing a key's domains is a use of the key, so only the account's manager gets it. It is left out for a viewer and for a member who did not connect the account. It is also left out for a key your customer's sign-in made, and for an account with no usable key. The account list never carries it.
- The read changes nothing.
If the provider refuses the key or the list fails,
more_domainsis left out and the account stays as it was. Check now is where you find a refused key. The provider's list is kept for a minute, so reading the account again does not call the provider again.
Which providers list their domains
Where a provider has a list call, we check the key by listing.
The console's Connect more domains shows the account's own list, and POST /v1/provider-accounts/{id}/zones returns it.
These providers list: Amazon Route 53, Azion, Binary Lane, Cloudflare, cPanel hosts and o2switch, DigitalOcean, DirectAdmin, DNSimple, 101domain, Domeneshop, Epik, Exoscale, Gandi, Gcore, GoDaddy, Hetzner, hosting.de, Hostinger, Huawei Cloud DNS, INWX, IONOS and united-domains, Joker.com, Loopia, Metaname, Mythic Beasts, NameBright, Namecheap, Name.com, netcup, NS1, OVHcloud, Plesk, Porkbun, Scaleway, Spaceship, Subreg, Vercel, webnames.ca, Websupport, WEDOS and Zone.ee.
A provider not named here answers that it cannot list.
Then you name one domain the key manages instead (see scope).
What each of the ten most recent lists holds, and what happens when a key may not:
| Provider | What the list holds | A key that may not list |
|---|---|---|
| Porkbun | Active domains with API Access turned on. A domain without API Access is left out, because Porkbun would refuse a change to it. | Checked with a domain you name. |
| Hetzner | The project's primary zones. A secondary zone is left out: its records come from another nameserver and the API refuses to change them. | Checked with a domain you name. |
| DigitalOcean | Every domain in the account. | A token with custom scopes needs domain:read. Without it, the key is checked with a domain you name. |
| Name.com | Every domain in the account. | Checked with a domain you name. If two-step verification blocks API access, the key is refused instead, and Name.com's API Access setting has to be switched on. |
| Gandi | The domains of the token's personal organization, which is all Gandi's list call returns. | Checked with a domain you name, and also when the list comes back empty, because an empty list cannot be told from a token whose domains sit in another organization. |
| DNSimple | The zones of the account the key writes to: the only account an account token has, or the first account of a user token that reaches several. A secondary zone is left out, because DNSimple does not let you change its records. | A scoped token needs the right to read zones (domains:*:read). Without it, the key is checked with a domain you name. |
| OVHcloud | Every DNS zone the key may read. | The key needs the right GET on /domain/zone. A key made with rights on /domain/zone/*, and a key from a secure sign-in, which is limited to one zone, may not have it, and is checked with a domain you name. An invalid or expired key is refused instead. |
| Vercel | The domains of the team the key was installed on, or of your personal account for a token that names no team. | A token that may not list, or a personal token that finds no domain (it may be a team member's), is checked with a domain you name. |
| Spaceship | Domains that are registered or in their first grace period. A domain still being registered, in its second grace period or in redemption is left out. | A key needs the domains:read scope. Without it, the key is checked with a domain you name. A sign-in through Spaceship's MCP server cannot list. |
| Hostinger | Active domains. A domain that is pending, expired or suspended is left out. | Checked with a domain you name. |
A key the provider refuses is never treated as "cannot list".
That covers a wrong, revoked or expired key.
The call answers 422 ProviderAuthenticationError, and the account is marked as needing a reconnect.
Who can manage an account
Anyone whose role operates applications may connect a key and read the accounts.
Other actions take an admin, an owner or the member who connected the account.
These are renaming it and changing its access, scope or domains.
They also include listing the domains its key reaches, connecting domains with it and giving it a new key.
The last are renewing it by signing in again, checking it and removing it.
The reason is that the key reaches zones the others were never given.
Removing it also deletes the key and detaches every domain that used it.
Anyone else gets 403, and nothing is stored or audited.
A key your customer's own sign-in made has no member who connected it, so only an admin or an owner manages it.
Each account says whether you may (can_manage).
The console shows a member who did not connect an account, and a viewer, the buttons off with one line that says why.
A name (label) is one to 80 characters, counted in characters.
We count after removing spaces, line breaks and a byte order mark at its ends.
It holds no control or invisible character.
That means no NUL, tab or line break, zero width space, byte order mark or text direction override.
An empty name, a longer one or one with such a character answers 400 invalid_request.
Nothing in the call is stored.
The console says the same words before it asks.
A viewer reads the accounts without what identifies your customer at their provider.
A key made at a secure sign-in shows them no agent_key.account (the customer number) and no agent_key.session_id.
A delegated agent token with domains:read reads them the way a viewer does, and less.
GET /v1/provider-accounts lists only the keys that serve the application its grant is bound to.
It never lists a key a customer made at their own sign-in.
It shows that application's connections only, and only the domains no other application of your workspace has connected.
can_manage is false and kept_access is empty.
?application_id= may only repeat the grant's own application, and answers 403 otherwise.
Its answers also leave out whatever could name a person or another application's domain:
- Who made a key.
made_by.byandcreated_byare left out, andmade_by.howstays. - The key's name.
agent_key.nameis left out for every key. The name holds an application's name. A key of the agent's own application can carry another application's name after a share. - The provider's words about a failure.
last_erroris left out for every key, because those words can name a domain of another application.statusandneeds_you.reasonstill say that the key needs attention. - The share list.
application_idsis always empty, since it names the workspace's other applications;application_idsays the key serves the agent's own. - A key made for another application and shared with the agent's own.
Its
labelreads<Provider> key, and it has noapplication_id. That's because the label the agent made it with (<Provider> key for <domain>) names the other application's domain.?q=searches only what the agent reads.
?domain= answers an empty accounts and saved_access in two cases.
One is a zone where another application holds a domain and the grant's own holds none.
The other is when the workspace's connections cannot be read.
It reads a key at its provider only for a zone the grant's own connections are in.
The agent reads GET /v1/connections/{id}/saved-access with domains:read.
No entry has a key_name, and a shared key gets the same neutral label.
It uses a key with POST /v1/connections/{id}:use-saved-access and domains:connect, for a connection of that application.
The account the use answers is read the same way as the list.
The audit log records the use as agent.acted under the agent's grant, once.
That happens whenever the records were written, the key linked or the write failed at the provider, whatever the answer.
A use refused before anything was sent, such as one with no records to write, leaves no row.
The same limits hold when the agent reads a connection.
On GET /v1/connections/{id}, the credential of a connection linked to a key carries no account, session_id or name.
A reach through a key made for another application reads <Provider> key.
No connection answer to an agent token carries end_user_ref, your id for the customer.
An API key reads all of it whole.
Sharing a key with another application is narrower still: only an admin or an owner may, not the member who connected the key. See which applications may use it.
Endpoints for API keys
| Call | Does |
|---|---|
POST /v1/provider-accounts | Connect a key: { provider, credential: { token }, access, scope, domains?, check_domain? }. Answers the provider's domains when it lists them. |
GET /v1/provider-accounts | Every account with access, domains, last use and expiry, what needs you first, plus kept sign-ins and Domain Connect authorizations grouped by provider. ?owner=workspace or end_user, ?q=, ?limit= and ?cursor= filter, search and page the list; end_user_keys counts your customers' keys. |
PATCH /v1/provider-accounts/{id} | Rename (one to 80 characters), change access, scope or domains, or the applications the key is shared with (application_ids, admin or owner only). A domain taken out stays connected, without continuous access. What each kind allows when it widens the account differs. |
POST /v1/provider-accounts/{id}/zones | The domains the key reaches. Takes whoever may manage the account. |
GET /v1/provider-accounts/{id} | One account with its domains. For its manager it also carries more_domains. |
POST /v1/provider-accounts/{id}/connect | Connect domains, each into its own application: { application_id?, domains }, where a domain is a name or { domain, application_id }. A domain is linked to the account once its records are written; a domain in a zone the key does not reach fails alone (zone_not_reached) and is not linked. |
POST /v1/provider-accounts/{id}/reconnect | A new key: { credential: { token, params? }, access?, check_domain? } for a pasted key, checked before it is kept (params replace the kept ones), or { method: "secure_sign_in", return_origin, consent_version } to renew a key made at a sign-in by signing in again. |
POST /v1/provider-accounts/{id}:check | Check now: read the key against its provider and answer { account, result }. Once a minute for an account. |
DELETE /v1/provider-accounts/{id} | Revoke: the key is deleted; its domains stay connected. Answers what that leaves: used_by and revoke_url. |
POST /v1/provider-accounts:sign-in | Start a secure sign-in that adds an account, with no domain. The console only. |
POST /v1/provider-accounts:oauth-start | Start a sign-in with the provider that adds an account: { provider, application_id?, return_origin }, answers { authorize_url, provider, flow, callback_origin }. The console only. |
A key the provider refuses marks the account needs_reconnect and each of its
domains records it on its timeline. A refusal that only concerns one zone (the
key works, but not for that domain) fails that domain and leaves the account
as it is. The console's Connected accounts page
shows all of this; Remember this key on the connect page keeps the key as a
continuous account.
Keys made at a secure sign-in
A secure sign-in can make a lasting API key at a domain's DNS provider. CustomDomain™ keeps it as a provider account of the workspace, checked and encrypted like any other. It has continuous access, with the domain's zone as its scope. Such an account is different in five ways:
- It belongs to one application.
application_idnames the application whose domain it was made for. Connecting another application's domain with it is refused with403, unless an admin shared the key with that application. - It can serve the application's other domains.
You or a teammate can start a sign in from the console.
The key it makes connects another domain of the same application with no second sign in and no second key.
CustomDomain™ first reads that domain's records with the key, and connects the domain only when the provider answers.
Its zone joins the key's scope once the records are written there.
A domain in another account at the provider is refused with
400, and needs its own sign-in. "Started in the console" means the console's own signed call. A sign-in your backend starts through the API makes a key that serves its one domain only. That holds even when the call names the console in its headers. A key your customer's sign-in made in the widget serves only the domain they agreed to. - It says where it came from.
originisbrowser_agent, andagent_keyholds its record, never the key. It holds thenameit was made with:CustomDomainand your application's name. It holds itsscopesandrights, which say what it can do beyond DNS:transfer,billingoraccount. It holds the provider'saccountidentifier when the page showed one, never an email address, and hidden from a viewer. It holds thesession_idthat made it, also hidden from a viewer. It holds when it was checked (verified_at) and when it ends (expires_at). It also holds the lastnotice, thereconnect_reason,reconnect_sent_atandrenewed_at. After a renewal it holdsold_key: "revoke_by_hand", plus the provider'srevoke_url. - It is renewed by a sign-in, not a pasted key.
Before its end, or once the provider refuses it, the account is
needs_reconnect. For a key your customer's sign-in made, your customer signs in again (reconnecting). For a key a member made at a sign-in in the console, a member who manages the account signs in again from the account. The account keeps its domains. In the console, Connected accounts shows it as Made at sign in. - Removing it deletes only our copy.
DELETE /v1/provider-accounts/{id}answersremoved_here,revoke_at_providerand the provider'srevoke_url. It sendscredential.removed. The key itself lives at the provider until you delete it there.
Add an account in the console
The console adds an account on its own page, Connect an account on Connected accounts
(/app/accounts/new), in three steps and then Connect N domains now. It is a page and not a dialog
so a flow this long works on a phone. Nothing is chosen for you.
-
Which company. Pick from a searchable list, or type a domain and the domain check finds the company. The list holds the companies with a way to add an account here: those whose
account_waysinGET /v1/providersis not empty. The step explains two words. A registrar is where you bought the domain. A DNS host runs the records that say where a name goes. A company with no way, such as one that signs in domain by domain, is named and sent to the connect page. The address/app/accounts/new?provider=<id>opens at step 2. For a company with no way, step 2 says so and links the connect page. -
How to connect. Only that company's ways, easiest first, as
account_wayslists them:- Sign in with <company> opens the company's own sign-in window, where you approve access. The account appears in Connected accounts as soon as you do, with every domain the sign-in reaches. See Add an account by signing in with the provider.
- Sign in opens the secure sign-in over the page, as the connect page's does. You sign in at the company, and we make the key and check it by listing the domains it reaches. The key waits in memory, never in an account, for ten minutes. See Add an account by secure sign-in.
- Paste an API key shows the company's steps and key page.
Check the key lists the domains the key reaches.
Only
list_not_supportedmeans the company cannot list. Any other refusal shows in its own words, and you stay on the key. Examples are a key the company refused, or a company that did not answer. A credential that is used once says why, and is kept for one time access only (Credentials that are used once).
-
What it may do.
- Which domains. Pick every domain in the account, or the ones you choose, ticked from the list or typed.
A key that cannot list its domains takes every domain only with one domain named (
check_domain). That's how we check the key. Typed domains are each checked. The button waits while a choice is empty. - Which applications. A pasted key is bound to no application, so every application may use it. A key a sign-in made is for the application chosen in step 2. Only an admin or an owner can share it with others (Which applications may use it).
- Access. Continuous or one time; a credential used once, and a deployment that keeps no keys, offer one time only.
A pasted key is made with
POST /v1/provider-accounts, and a sign-in's key withPOST /v1/browser-sessions/{id}:keep. A key that replaced the one an account held is named, so you delete the right one. - Which domains. Pick every domain in the account, or the ones you choose, ticked from the list or typed.
A key that cannot list its domains takes every domain only with one domain named (
Then Connect N domains now calls POST /v1/provider-accounts/{id}/connect (Connect many domains at once).
Each ticked domain goes into the application you choose, among the ones the key may use, at most 200 a call.
The page shows each domain's result: Connected, Already connected, or why not.
It offers a retry of the ones that failed.
Sometimes a call after the first is refused, for example for too many requests.
Then the domains it and the later calls would have carried are listed as failed with the reason.
So Try the ones that failed again offers them.
A call that answers 200 with no result for its domains says nothing about them.
The page lists them as "not confirmed" ("No result came back, so we can't say if it connected.").
It offers them again with the failed ones.
Trying again is safe, because the control plane answers Already connected for a domain it has.
With more than one application, Put them in is held while any are not confirmed ("Trying again puts them in the same application.").
So a domain that did connect is never connected into a second application.
If the first call is refused, nothing is connected and the page stays as it was, with the reason.
If every call came back with no result, it stays as it was too, says so, and links to the account's page.
After a sign-in, the offer is the key's domains the workspace has not connected yet (More domains in the account).
Later leaves them for the account's own page.
A sign-in that stops before the keep is cancelled.
It stops when the window closes, on Back or Start again, when you leave the page, or when ten minutes pass.
The page then says which key it made, with the provider's page that deletes it (left_key, see below).
Start again keeps saying so even when the key was made a moment before the page read it.
Back to the first step carries the notice and shows it above Which company, because the key is still live at the company.
Choosing that company again names the key on its step 2 until you start another sign-in.
Choosing another company leaves the notice behind.
The page needs the member role or above.
Add an account by signing in with the provider
Some providers offer a sign-in other apps can use (OAuth). For them, Connected accounts shows Sign in with <provider> as the first way to add an account. Pick it and approve access in the provider's own window. The account then appears in Connected accounts. You don't make or paste an API key.
- Which providers. Cloudflare, DigitalOcean, DNSimple, Linode, Netlify, Vercel and WordPress.com.
GET /v1/providerslistsoauthfirst in a company'saccount_wayswhere it is offered. Azure DNS, Google Cloud DNS, Porkbun and OVHcloud are not offered here, because their sign-in starts from a domain. Connect a domain with them from the connect page instead. - What is kept. The access the provider gives, encrypted, with a refresh token, so the account keeps working without you signing in again. A sign-in that gives no refresh token adds no account.
- What it may do. Every domain the sign-in reaches (scope
all), continuous access. Connect domains with it right away. - When it stops working. If the provider refuses the saved sign-in, the account shows Needs a new sign-in (
needs_reconnect). Add it again with Sign in with <provider>. For DNSimple and Vercel this renews the same account. For the others it adds a new one, and you remove the old one. - Removing it also revokes its access at the provider.
- Who can start it. An owner, an admin or a member, from the console only.
POST /v1/provider-accounts:oauth-startstarts it; a pasted key or a secure sign-in cannot replace the key of an account made this way (409).
If you decline, close the window, or the provider can't keep you signed in, no account is added and the page says so.
Add an account by secure sign-in
The console's Connected accounts can add an account without a pasted key (the page that does it). The person signs in to the provider in a temporary browser, and CustomDomain™ makes the API key itself. It checks the key by listing the domains it reaches. Then it asks which of those domains the account may use. The account is kept only after that answer. Nothing is kept before it, so a sign-in that is left alone or cancelled adds no account.
It is for the console only.
POST /v1/provider-accounts:sign-in answers 201 with { session_id, popup_url }.
It needs an API key that carries the console's signed visitor forward, for an owner, an admin or a member.
A viewer is refused with 403.
The X-CustomDomain-Client header and the Origin alone start nothing.
A widget token, an end user's token, a delegated agent token and the operator's key are refused with 403 browser_account_unavailable.
Your own backend's API call does not start one, so add the key with POST /v1/provider-accounts instead.
GET /v1/providers lists each company's account_ways, easiest first.
oauth comes first where signing in with the provider is offered.
Then secure_sign_in, where the deployment runs it for that company, then api_key.
Once the key is made, the member who started the sign-in reads it with GET /v1/browser-sessions/{id}.
It shows state key_ready, the zones the key lists, what the key is, and when the ten minute wait ends.
They confirm with POST /v1/browser-sessions/{id}:keep:
{ "scope": "selected", "domains": ["example.com"], "access": "continuous", "application_ids": [] }scopeis always named.allof the account's domains, orselectedones, each a domain the key lists (422domain_not_listedotherwise).accessiscontinuous(the default) orone_time; a credential that is used once isone_timeonly.- The account is the workspace's own.
originisbrowser_agent, andmade_by.howisconsole_sign_in. It is bound to the application the sign-in named, or serves every application when it named none.application_idsshares the key with other applications, for an admin or an owner only. - One key per provider account.
The workspace may already hold a continuous key for the same provider account and application.
Then the new key is swapped into that account (
200,swapped: true). The old key stays at the provider, and the account says so (old_key: "revoke_by_hand"). The answer also names it inreplaced_key, so you delete the right one.replaced_keyholds thenameit was made with and thepagewhere the provider lists and deletes keys. The two keys carry different names, because an account sign-in names its key to the second. Two sign-ins for the same account in the same second would share one name. The chosen domains join the account's scope and never narrow it. Every swap takes an admin, an owner or the member who connected the account, whether or not it widens the scope. Another member's keep is403and the key still waits. So they can cancel the sign-in and be told which key to delete. GoDaddy is the exception for now: its second sign-in adds a second account. - A suspended workspace adds none.
While an operator has suspended the workspace, starting a sign-in and keeping its key are
403workspace_suspended. The read and the cancel still work. So you can abandon one under way and have its key named. - An abandoned sign-in names its key.
POST /v1/browser-sessions/{id}:cancelwith the API key drops the key from our memory, and so do the ten minutes passing. It answersleft_key: the name it was made with and the provider's page that deletes it. The key itself lives at the provider until you delete it there.
Every call about the session is for the member who started it, in their workspace.
Another member's session, another workspace's and a connect sign-in's all answer 404.
Every account made, swapped or shared is in the audit log.
The rows are provider_account.created, .key_replaced (with the replaced key's name as old_key_name), .updated and .shared.
Renew an account by signing in again
A key made at a secure sign-in in the console is renewed the way it was made: by signing in to the provider again. The account stays the same account. It keeps its id, its domains, its scope, its access and the domains linked to it, and only its key changes.
POST /v1/provider-accounts/{id}/reconnect takes method. The default,
api_key, is the paste for a key a person pasted. secure_sign_in starts the
same sign-in as adding an account, for the
account's own provider and application:
{ "method": "secure_sign_in", "return_origin": "https://app.example.com", "consent_version": "cb-3" }It answers 201 with { session_id, popup_url }.
GET /v1/browser-sessions/{id} names the account the session renews in renews_account_id.
When the key is made and checked, confirm it with POST /v1/browser-sessions/{id}:keep and an empty body, {}.
The new key goes into the same account (200, swapped: true).
replaced_key names the old key so you delete it at the provider.
The account is active again, and its daily check starts afresh.
A one time account gets a new hour.
- Who may. The console's own signed call, for an admin, an owner or the member
who connected the account. Another member and a viewer get
403, and so does any caller that is not the console. - Which keys. A key made at a sign-in in the console. A key you pasted is
renewed by pasting a new one (
409). A key your customer's own sign-in made is renewed by your customer, never from the console (403). - It must be the same provider account.
Where the provider names the account, the new key's account must be the same.
Where it does not (IONOS), the new key must list every domain the account holds.
For an account of every domain, it must list the domains linked to it.
A key of another account answers
422different_accountand changes nothing. The key stays pending, and cancelling the sign-in names it so you can delete it at the provider. An account that holds no domain and has no account number gives nothing to compare. It answers422account_not_verifiablethe same way. Remove the account and add it again with a new sign-in. - Nothing else changes. A body that names
scope,domains,accessorapplication_idsis400: change those withPATCH. - Audited.
provider_account.key_replaced, withviasign_inandrenewedtrue.
Remove an account
DELETE /v1/provider-accounts/{id} deletes CustomDomain™'s copy of the key and
the account. It says what that leaves:
{ "id": "pacct_...", "removed_here": true, "revoke_at_provider": true, "revoked": true, "used_by": 2, "domains_kept_connected": 2, "revoke_url": "https://..." }removed_hereis alwaystrue: CustomDomain™'s copy of the key is gone.revoke_at_provideristruewhen the key still works at the provider until you delete it there, so do that too.revokedis deprecated and only ever meant removed here; it does not say the key stopped working.used_byis how many domains used the account. They stay connected and keep serving, without continuous access; each recordsaccess_revokedon its timeline.domains_kept_connectedis the same number.revoke_urlis the provider's page where the key itself is deleted, for a key you pasted as for one made at a sign-in. CustomDomain™ cannot revoke a key at the provider, so the key lives there until you delete it. The field is absent when the provider has no such page on file.
Removing an account takes whoever manages it: an admin, an owner or the member who connected it.
For a key your customer's sign-in made, it takes an admin or an owner.
Anyone else, a viewer included, gets 403, and nothing is deleted or detached.
The account's sheet in the console
Open an account in Connected accounts for its sheet. It has everything above for that account, in one place, and offers each thing to exactly the people who may do it. What it offers depends on how the key was made:
| A key you pasted | A key made at a secure sign-in | A key your customer made | |
|---|---|---|---|
| Rename | Yes | Yes | Yes |
| Domains it may configure | Tick from the provider's list, or type them where the provider cannot list | Tick from the provider's list; each domain you add is read with the key first, and one it does not reach is named and nothing is saved | Take domains out. Never added to, and the provider is never asked |
| Applications that may use it | Every application may use it | Its own application, and any other an admin or an owner ticks | Its own application only. Never shared |
| Connect more domains | Yes | Yes | No |
| Check now | Yes, for a key we hold (not a one time key) | Yes | No. The daily check reads it |
| New key | Replace key: paste one | Sign in again: the same account, a new key | Your customer signs in again |
| Remove | Yes | Yes | Yes |
- Change which domains an account may configure is open the account, tick, Save: the list is in the sheet, not behind a button. Save stays off until something changed and at least one domain is chosen; to stop using an account altogether, remove it.
- Connect more domains lists the domains the key reaches that you have not
connected (
more_domains). Type any other domain or subdomain, choose the application, and connect. Each domain says what happened, and you can try the failed ones again. - Sign in again opens the provider's sign-in over the page and makes a new key for the same account. When it is made, Use the new key swaps it in. The account keeps its name, domains and settings. The old key is named, with the page where you delete it. See renewing an account.
- Remove says how many domains use the account (they stay connected), then links the provider's page where the key itself is deleted. See removing an account.
- Check now reads the key at the provider and says it works, was refused, or could not be reached. A line under the facts says what the last check found. See Check now.
- Who holds the limit is one line, from
enforced_by. For a provider whose key reaches the whole account: "CustomDomain™ uses this key only for the domains you pick. GoDaddy itself lets it reach the whole account." For one whose key is made for chosen domains: "Cloudflare itself limits this key to the domains it was made for." See who enforces the limit.
A button you may not use shows as off, with the reason under the buttons. A member who did not connect it sees Only admins, owners and whoever connected this account can change it. For a customer's key, it reads Only admins and owners can change a key your customers made. For the applications, it reads Only admins and owners can choose which applications use a key. A viewer sees Members, admins and owners can change domains. Every change is in the audit log under who made it. A member is recorded under their own member ID. The person who created the workspace works in the console with the workspace's key. Their changes are recorded under that key's ID, never the key itself.
What needs you
GET /v1/provider-accounts lists the accounts that need someone first, each
with needs_you.reason, then the most recently used, the never used last,
newest first:
needs_you.reason | What it means | What to do |
|---|---|---|
refused | The provider refused the key. | Give the account a new key, or sign in again for a key made at a sign-in, or remove it. |
expired | The key reached its end, or a one time key's hour passed with the key unused. | Sign in again, give it a new key, or remove it. |
check_failed | The daily health check of the key failed three times in a row without the provider refusing it (a timeout, a server error, a domain the key no longer reads). The key may still work. | Call Check now (POST /v1/provider-accounts/{id}:check) to try it. If it keeps failing, check the provider's status and that the account still holds its domains. |
expiring | A key made at a sign-in ends within 30 days (until says when). | Sign in again before then. |
one_time_window | A one time key waits for its domains to be connected, until until. | Connect the domains now. |
no_domains | A continuous key the workspace holds that no domain uses. | Connect domains with it, or remove it. |
An account that needs nothing has no needs_you.
Health checks
You should find a key that stops working when it stops, not weeks later when something tries to use it. Once a day, CustomDomain™ reads each continuous account's key with one cheap call. That call is the provider's list of domains where it gives one, or else a read of one domain the account covers. The check writes nothing at the provider. It does not count as using the key, so last used does not move.
Every account the check applies to answers health:
health.state | What it means |
|---|---|
ok | The last check worked. checked_at says when. |
failing | The last check, or more, could not reach a verdict. failures counts them in a row. From the third the account is in what needs you as check_failed. |
refused | The provider refused the key. The account is needs_reconnect. |
unchecked | No check has run yet. A key connected before the checks began waits for its first one, within a day. |
A one time account, and an account that holds no key, has no health. A
viewer and a delegated agent token read it as a member does: it names no one and
no domain.
What a check finds:
- The provider accepts the key. The failures are forgotten, and the next check is a day later, give or take two hours. So a thousand accounts do not all fall due at once.
- The provider refuses the key. The account becomes
needs_reconnect. Each domain it covers records it on its timeline, and the workspace gets one inbox item. A key made at a secure sign-in also asks your customer to sign in again. A refused key is not checked again until you give the account a new key or call Check now. When the provider refuses to list the domains, CustomDomain™ reads one domain before it calls the key refused. So a key made without the right to list is not flagged. - Anything else goes wrong. That covers a timeout, a server error, a rate limit, or a domain the key cannot read.
A domain it cannot read may only mean that domain is out of the key's reach.
The check tries again after 1 hour, then 4, 12 and 24 hours, then every 48 hours.
From the third failure in a row, the account is in what needs you as
check_failed. The key stays active, because a failing check does not stop repairs.
A key your customer's own sign-in made is never listed. It is checked with one read of a zone it already serves, because its account holds domains you were never given.
Giving an account a new key, reconnecting it, or making a one time key continuous starts its checks over, a day from then.
Check now
POST /v1/provider-accounts/{id}:check runs the same check on request, and records what it finds the same way.
It takes the workspace's API key, plus an admin, an owner or the member who connected the account.
A widget token or an agent token is refused.
It answers the account and a result:
{ "account": { "id": "pacct_...", "status": "active", "health": { "state": "ok", "failures": 0 } }, "result": "ok" }ok: the provider accepted the key. A pasted key that the provider had refused and that works again returns toactive, and the change is in the audit log. A key made at a secure sign-in keeps its status, because it is renewed by signing in again.refused: the provider refused the key, and the account is nowneeds_reconnect.unreachable: the provider could not be asked, or answered with an error that is not a refusal.messagesays what. The failure counts toward the backoff.
Every check that asked the provider is in the audit log as provider_account.checked.
The row holds who asked, the account and the result (ok, refused or unreachable), whatever the answer was.
It never holds the key or the provider's own words.
A call that never asked the provider leaves no row.
That covers a 403 and a 429.
It also covers a 409 for a one time key, an account with no key, or nothing to read the key against.
It covers a request that ended before the provider was asked, too.
An account's key can be checked once a minute.
A second call answers 429 rate_limited with Retry-After: 60.
Each check is also one read of the workspace's hourly limit.
Once that is spent, the call answers 429 reach_quota.
It asks the provider nothing, records nothing and keeps no minute, so you can check the same account as soon as the hour turns.
A key your customer's sign-in made answers 403, because the daily check reads it, as above.
A one time key answers 409.
An account whose provider cannot list its domains, and which covers none, answers 409 nothing_to_check.
Connect a domain with it first.
An account that changed while its key was being checked also answers 409.
For example, its key was replaced, or someone edited it in that moment.
Nothing is recorded and the minute is not used up, so call Check now again at once.
A call that ends after the provider was asked does use up the minute.
That happens when the connection dropped before the answer, or the answer was a 500.
A request that had already ended when the check was about to start answers 503.
It asks the provider nothing, takes nothing from the hourly limit, and does not use up the minute.
How a key was made and who added it
Every account says how its key was made and by whom, in made_by:
howsays how the key was made.pastedmeans a person pasted the key.console_sign_inmeans it was made at a secure sign-in you or a teammate started in the console.widget_sign_inmeans it was made at your customer's own sign-in, in the widget or one your backend started for them through the API.bynames who made the key. It is the member's e-mail, ora customerfor a key your customer's sign-in made (never their id). For a key an API call pasted, it is the API key's name. It is absent when it was not recorded. A delegated agent token's answer always leaves it out, because an agent has no need to know which person made a key.howstays.
?owner=workspace keeps the keys your workspace holds: pasted, or made at a sign-in started in the console.
?owner=end_user keeps the keys your customers' own sign-ins made.
end_user_keys counts those keys and the customers they belong to (distinct end_user_ref).
It counts before owner, q and paging apply, so a console can show them as one row.
?q= keeps the accounts whose label, scope domain or linked domain holds the text.
For a member, it also matches account_ref, agent_key.account or end_user_ref.
A viewer never matches those, because they are not shown one.
?limit= (1 to 200) and ?cursor= (the previous answer's next_cursor) page the list.
Without limit, the answer holds every account.
?domain= answers the resolver's order in full, so limit and cursor with it are 400.
Who enforces the limit
A key is held to the account's scope either by the provider or by
CustomDomain™, and enforced_by says which:
provider: the key itself reaches only the zones it was made for. A Cloudflare API token names its zones. Porkbun switches API access on per domain. An IAM policy names the Route 53 hosted zones an access key may change.customdomain: the key reaches the whole account at the provider. That's true for GoDaddy, IONOS, Namecheap, Name.com and the rest. CustomDomain™ uses it only for the domains in the scope. Narrowing the scope changes what CustomDomain™ does with the key, not what the key could do.
Which applications may use it
A key made at a secure sign-in belongs to one application (application_id) and serves its domains alone.
It serves another application of the workspace only when an admin shares it.
So a workspace with two applications can sign in once for a provider account and use that key for both.
Send application_ids to PATCH /v1/provider-accounts/{id}: the whole list of
other applications that may use the key, besides its own.
{ "application_ids": ["app_marketing"] }- Who may. An admin or an owner. The member who connected the key manages it,
and still gets
403here. Anyone else gets403too. - Which keys. A key bound to one application. A key your customer's own
sign-in made is never shared (
403): it acts only for that customer in their application. A key you pasted that is not bound to an application already serves every one, so naming an application answers422serves_every_application. - Which applications. Each must belong to your workspace, or the call
answers
404. The key's own application always serves, so naming it, naming an application twice or sending a blank changes nothing. At most 100 per call. - It replaces the set. Leave an application out to take the key back from it,
and send
[]to share with none. The answer'sapplication_idsis the list now in force. - What a share allows. The shared application's domains can use the key like its own.
The saved-access list offers it for the second application's domains, and never for a third.
POST /v1/provider-accounts/{id}/connecttakes that application's id. A second secure sign-in for the same provider account, from the shared application, swaps its key into the shared account instead of adding a second one. Reconnecting a domain of the shared application renews the key in the same account. - What taking it back does. The domains of that application that used the key stay connected, without continuous access.
Each records
access_revokedwith the reasonunsharedon its timeline. - Audited. Each application shared writes
provider_account.sharedand each taken outprovider_account.unshared, with the applications the key served before and after and the ones that changed.
Whose key it is, and saved access
Every account says whose it is.
owner_kind is workspace for a key your workspace holds.
That's one you pasted, or one made at a sign-in you or a teammate started in the console.
It is end_user for a key your customer's own sign-in made.
A key a customer made acts only for that customer, in the application where they made it.
You can narrow it or remove it.
You cannot use it, list the domains it reaches or widen it.
account_ref is the provider account the key belongs to.
end_user_ref is your id for the customer, when the sign-in named one.
A viewer sees neither.
Saved access answers "which kept key can act for this domain, for me" in one place. So a second domain at the same provider does not start a second sign-in:
GET /v1/connections/{id}/saved-accesslists them, best first. A key is listed when it is at the domain's provider, kept (continuous) and still working. It must also serve the connection's application, and you must be allowed to use it. A key whose scope already holds the domain's zone isready. A key made at a sign-in started in the console may also be listed withready: false. That happens after one read with it showed it reaches the zone. Using it adds the zone to its scope. At most three such reads happen per call, and each answer is kept ten minutes. There is one entry per provider account.POST /v1/connections/{id}:use-saved-accesswith{"account_id": "..."}writes the domain's records with that key. It links the key once the write worked. A write that fails links nothing and leaves the key's scope as it was. It records the failure on the domain (error_codeanderror_message):502 saved_access_write_failed, with the provider's words. A provider that writes one record set at a time can fail after the first. So the zone may hold some of the records even though the call failed. An account that cannot act for the domain is409 saved_access_not_usable. A key not read because the workspace's hourly limit was spent is429 reach_quotainstead. Nothing is written.rails.saved_accessonPOST /v1/domains:checkis the same list for an API key caller.recommended_railis thensaved_access. An end user's widget token gets it only for that customer's own keys. The rules are in A returning customer's own key. An AI agent uses the same two routes through the MCP toolsfind-saved-accessanduse-saved-access. It useslist-provider-accountsfor the accounts.discover-providerreportsrails.savedAccessand says so.GET /v1/provider-accounts?provider=&domain=keeps the accounts that can act for a domain.
A secure sign-in or a provider sign-in for a domain that a saved key can already
act for answers 409 saved_access_available before anything starts. Send
new_sign_in: true to sign in with another account. Your customers' widget
sessions are not refused this way: a customer's own saved key is offered to them,
but the offer is not a refusal.
A returning customer's own key
A key your customer made at their own secure sign-in is reused only for that customer, in the application where they made it.
It is never reused for anyone else: not another customer, not you or a teammate, and not an AI agent.
When the customer comes back with another domain, we can offer their own key instead of a new sign-in.
rails.saved_access on the check and GET /v1/connections/{id}/saved-access make that offer.
They offer it only when all of this holds:
- the widget token is bound to the domain and was minted with your id for the
customer (
end_user_ref). A sample'suser_42orcustomer_123does not count: it is a placeholder, so one customer could otherwise be offered another's key; - the application allows it:
end_user_saved_accessis on (on by default; a test mode application never offers a key). Turn it off withPATCH /v1/applications/{id}or with Use their saved access under Widget → Ways to connect (the setting); - The customer can be told by email that their key was reused.
That needs three things.
First, the end user notices feature is on.
Second, we have their address.
You gave it when you minted the token (
end_user_email), or the domain's connection holds one and names this customer. An address on a connection that names no customer does not count, because any customer's token could have set it. Third, the application's mail can be sent. Without the email, nothing is offered. - The key was made at a sign-in started with a token minted with that same
end_user_ref. Any such token counts, not only the one asking now. Either its scope already holds the new domain's zone (ready: true), or one read with it shows it reaches that zone (ready: false). - the key is not at GoDaddy. Reuse there is held until GoDaddy gives written permission (why).
The entry names the provider and from_domain, a domain of theirs the key already serves.
It says nothing else about the key: no key name and no application.
It uses the neutral label <Provider> key in place of any name a member gave the account.
Any miss leaves the customer on the usual sign-in.
For now it is an offer only.
A customer's token cannot yet write a domain's records with the key (409 saved_access_not_usable), and the sign-in is not refused.
The tap of consent for each domain, and the email after each use, come with that step.
A second secure sign-in for a provider account you already hold a key for does not add a second row.
That holds when it comes from the application the key belongs to, or one it is shared with.
Its key is swapped into the existing account, and the domain's zone joins that account's scope.
The key it replaces still lives at the provider, unless it was the same key.
So the account shows old_key: "revoke_by_hand" with the provider's revoke_url.
CustomDomain™ never revokes a key itself.
If the write that follows the sign-in fails, the account keeps the new key (and old_key).
The zone leaves its scope again, unless the account covered it before, and the domain records the failure.
An account other domains use is never removed for one failed write.
GoDaddy is the exception for now: each sign-in there keeps its own key (why and what it means).
DNS hosting uses an account at the registrar
DNS hosting changes a domain's nameservers at its registrar.
Where the workspace keeps an account at that registrar, a nameserver move can use its key to make the change.
So nobody signs in again.
It works only for the domains the account is given for (scope).
A key made at a secure sign-in works only for domains of the application it was made for.
Each use is in the audit log as credential.used_for_nameservers.
Without such an account, the move goes through a secure sign-in at the registrar, or the person sets the nameservers by hand.
An account at the company that runs the domain's DNS is never used for the change, when that company is not the registrar.
Audit log
The workspace's audit log records every change to a provider account.
It also records every use of its key beyond the records it wrote.
Read it with GET /v1/audit, or on the console's Activity page.
It names who did it as the server knows them, never the key.
A call with a member's own key is recorded under that member's ID.
A call with any other API key is recorded under that key's ID.
That covers the workspace's key, which the person who created the workspace uses in the console, and one an integration holds.
An agent is recorded under agent:<grant id>:
| Event | When |
|---|---|
provider_account.created | A key is kept: pasted, or made at a secure sign-in. |
provider_account.updated | Its label, access, scope or domains change, with the values before and after. Also when Check now finds that a refused pasted key works again and returns it to active (status before and after, via: check_now). |
provider_account.domain_added | A key made at a sign-in in the console starts serving another domain's zone. |
provider_account.relinked | A domain the application already had now uses this account. |
provider_account.key_replaced | It gets a new key: pasted, or made when someone signed in again. |
provider_account.shared | An admin or an owner lets another application use the key. Names the applications it serves before and after, and the ones just shared (application_ids). |
provider_account.unshared | An admin or an owner takes that back. Same fields. |
provider_account.checked | A key is checked on request (Check now). The provider and the result: ok, refused or unreachable. One row for each check that asked the provider, never the key or the provider's words. |
provider_account.domains_connected | A call to connect many domains connected at least one. The provider and the names of the domains connected, in one row for the call. A call that connected none leaves no row. |
provider_account.removed | Our copy is deleted: revoked, its last domain removed, or the write after a sign-in failed. |
agent.acted | An agent changed a domain's DNS under its grant: it used a saved key for a domain (used a saved key), re-applied a domain's records (re-applied a domain's records) or moved a domain's nameservers, or back (moved a domain's nameservers, moved a domain's nameservers back). The row is agent:<grant id> in the actor. |
credential.used_for_nameservers | A nameserver move, or a move back, uses its key. |