CustomDomain Docs
Connect flow

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-accounts or 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 answers via: "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 409 and 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 429 reach_quota with Retry-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 answers 429 reach_quota. It writes nothing, and does not answer 409 saved_access_not_usable. Wait for Retry-After and 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:

KindWidening its domains or scope
Pasted (pasted): you made the key and pasted itAny 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:

  1. the application named for that domain;
  2. the call's application_id, which you can leave out;
  3. 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 403 before 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 answers 403 ("this key is not shared with this application; an admin or an owner can share it"). An application that is not your workspace's answers 404.
  • Every domain is inside the account's scope. A domain outside it answers 400 and 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 as example.com for shop.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 answers 422 zone_not_reached, with those domains in domains. A provider that cannot answer (a timeout or a server error) answers 503, never a refusal of the key. Both are the answers PATCH gives, and nothing is written. A call reads at most 20 such zones, once each, and answers 400 too_many_domains_to_check beyond that. To widen the scope on its own, use PATCH /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_domains is 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:

ProviderWhat the list holdsA key that may not list
PorkbunActive 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.
HetznerThe 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.
DigitalOceanEvery domain in the account.A token with custom scopes needs domain:read. Without it, the key is checked with a domain you name.
Name.comEvery 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.
GandiThe 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.
DNSimpleThe 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.
OVHcloudEvery 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.
VercelThe 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.
SpaceshipDomains 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.
HostingerActive 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.by and created_by are left out, and made_by.how stays.
  • The key's name. agent_key.name is 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_error is left out for every key, because those words can name a domain of another application. status and needs_you.reason still say that the key needs attention.
  • The share list. application_ids is always empty, since it names the workspace's other applications; application_id says the key serves the agent's own.
  • A key made for another application and shared with the agent's own. Its label reads <Provider> key, and it has no application_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

CallDoes
POST /v1/provider-accountsConnect a key: { provider, credential: { token }, access, scope, domains?, check_domain? }. Answers the provider's domains when it lists them.
GET /v1/provider-accountsEvery 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}/zonesThe 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}/connectConnect 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}/reconnectA 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}:checkCheck 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-inStart a secure sign-in that adds an account, with no domain. The console only.
POST /v1/provider-accounts:oauth-startStart 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_id names the application whose domain it was made for. Connecting another application's domain with it is refused with 403, 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. origin is browser_agent, and agent_key holds its record, never the key. It holds the name it was made with: CustomDomain and your application's name. It holds its scopes and rights, which say what it can do beyond DNS: transfer, billing or account. It holds the provider's account identifier when the page showed one, never an email address, and hidden from a viewer. It holds the session_id that 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 last notice, the reconnect_reason, reconnect_sent_at and renewed_at. After a renewal it holds old_key: "revoke_by_hand", plus the provider's revoke_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} answers removed_here, revoke_at_provider and the provider's revoke_url. It sends credential.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.

  1. 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_ways in GET /v1/providers is 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.

  2. How to connect. Only that company's ways, easiest first, as account_ways lists 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_supported means 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).
  3. 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 with POST /v1/browser-sessions/{id}:keep. A key that replaced the one an account held is named, so you delete the right one.

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/providers lists oauth first in a company's account_ways where 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-start starts 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": [] }
  • scope is always named. all of the account's domains, or selected ones, each a domain the key lists (422 domain_not_listed otherwise). access is continuous (the default) or one_time; a credential that is used once is one_time only.
  • The account is the workspace's own. origin is browser_agent, and made_by.how is console_sign_in. It is bound to the application the sign-in named, or serves every application when it named none. application_ids shares 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 in replaced_key, so you delete the right one. replaced_key holds the name it was made with and the page where 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 is 403 and 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 403 workspace_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}:cancel with the API key drops the key from our memory, and so do the ten minutes passing. It answers left_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 422 different_account and 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 answers 422 account_not_verifiable the same way. Remove the account and add it again with a new sign-in.
  • Nothing else changes. A body that names scope, domains, access or application_ids is 400: change those with PATCH.
  • Audited. provider_account.key_replaced, with via sign_in and renewed true.

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_here is always true: CustomDomain™'s copy of the key is gone. revoke_at_provider is true when the key still works at the provider until you delete it there, so do that too. revoked is deprecated and only ever meant removed here; it does not say the key stopped working.
  • used_by is how many domains used the account. They stay connected and keep serving, without continuous access; each records access_revoked on its timeline. domains_kept_connected is the same number.
  • revoke_url is 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 pastedA key made at a secure sign-inA key your customer made
RenameYesYesYes
Domains it may configureTick from the provider's list, or type them where the provider cannot listTick 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 savedTake domains out. Never added to, and the provider is never asked
Applications that may use itEvery application may use itIts own application, and any other an admin or an owner ticksIts own application only. Never shared
Connect more domainsYesYesNo
Check nowYes, for a key we hold (not a one time key)YesNo. The daily check reads it
New keyReplace key: paste oneSign in again: the same account, a new keyYour customer signs in again
RemoveYesYesYes
  • 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.reasonWhat it meansWhat to do
refusedThe 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.
expiredThe 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_failedThe 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.
expiringA key made at a sign-in ends within 30 days (until says when).Sign in again before then.
one_time_windowA one time key waits for its domains to be connected, until until.Connect the domains now.
no_domainsA 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.stateWhat it means
okThe last check worked. checked_at says when.
failingThe 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.
refusedThe provider refused the key. The account is needs_reconnect.
uncheckedNo 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 to active, 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 now needs_reconnect.
  • unreachable: the provider could not be asked, or answered with an error that is not a refusal. message says 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:

  • how says how the key was made. pasted means a person pasted the key. console_sign_in means it was made at a secure sign-in you or a teammate started in the console. widget_sign_in means it was made at your customer's own sign-in, in the widget or one your backend started for them through the API.
  • by names who made the key. It is the member's e-mail, or a customer for 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. how stays.

?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 403 here. Anyone else gets 403 too.
  • 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 answers 422 serves_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's application_ids is 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}/connect takes 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_revoked with the reason unshared on its timeline.
  • Audited. Each application shared writes provider_account.shared and each taken out provider_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-access lists 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 is ready. A key made at a sign-in started in the console may also be listed with ready: 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-access with {"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_code and error_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 is 409 saved_access_not_usable. A key not read because the workspace's hourly limit was spent is 429 reach_quota instead. Nothing is written.
  • rails.saved_access on POST /v1/domains:check is the same list for an API key caller. recommended_rail is then saved_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 tools find-saved-access and use-saved-access. It uses list-provider-accounts for the accounts. discover-provider reports rails.savedAccess and 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's user_42 or customer_123 does not count: it is a placeholder, so one customer could otherwise be offered another's key;
  • the application allows it: end_user_saved_access is on (on by default; a test mode application never offers a key). Turn it off with PATCH /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>:

EventWhen
provider_account.createdA key is kept: pasted, or made at a secure sign-in.
provider_account.updatedIts 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_addedA key made at a sign-in in the console starts serving another domain's zone.
provider_account.relinkedA domain the application already had now uses this account.
provider_account.key_replacedIt gets a new key: pasted, or made when someone signed in again.
provider_account.sharedAn 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.unsharedAn admin or an owner takes that back. Same fields.
provider_account.checkedA 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_connectedA 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.removedOur copy is deleted: revoked, its last domain removed, or the write after a sign-in failed.
agent.actedAn 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_nameserversA nameserver move, or a move back, uses its key.

On this page