DNS Provider Onboarding

Overview

Entri Network lets DNS providers (registrars, hosting companies, DNS platforms) register their APIs with Entri so that when a mutual user launches the Entri modal, Entri can configure DNS records automatically — no copy-paste required. You configure your integration through the Setup wizard. It walks you through five steps:

Provider profile — how customers see you.
Domain detection — how Entri knows a domain is yours.
Authentication — how Entri logs into your API.
DNS endpoints — the routes Entri calls to read and write DNS records.
Review & submit — a final check before you go live.

You can move between steps freely. Each step is saved independently, and you must complete the required fields in a step before continuing. Once you’re live, this same page becomes your editable settings. This page documents every field in the wizard.

Step 1 — Provider profile

Tell us who you are. This is the brand customers see when they connect a domain to an app. It’s also how Entri reaches you if something goes sideways.

Brand

Field	Required	Description
Provider name	✓	The name shown to customers in the connect dialog (e.g. `DNSimple`, `Cloudflare`)
Website	—	Your company website URL
Support email	✓	Where customers reach you for connection help
Logo	—	Upload a square PNG or SVG, at least 64×64. Shown to users when they connect their domain via the Entri modal
Brand color	—	Used for buttons and highlights in the connect dialog. Click the swatch to open the color picker, or enter a hex value (e.g. `#006fee`)

Your provider name may be pre-filled if Entri already has a record for your platform. You can edit it before saving.

Manual fallback

Optional — a link to your own DNS instructions, in case Entri ever needs to send a customer to you to finish a connection.

Field	Required	Description
Manual instructions URL	—	A link to your DNS help docs (e.g. `https://help.yourcompany.com/dns`)

Preview

Use Preview in Entri to see a snapshot of the provider card customers will see in the Entri picker.

Step 2 — Domain detection

Help Entri recognize your customers’ domains. When someone enters their domain in Entri, we need to know it’s managed by you. Pick one or both methods — Entri tries each in order.

Nameserver match

If a domain’s nameservers are yours, Entri knows it’s on your service.

Field	Required	Description
Your nameservers	✓	One nameserver hostname per line (e.g. `ns1.example.com`). Wildcards (e.g. `ns*.example.com`) are supported

DNS lookup (recommended)

Add a DNS record Entri can verify on every domain you manage. Useful if your nameservers vary.

Field	Required	Description
DNS Record Type	✓	The record type Entri checks: `TXT` (recommended), `CNAME`, `A`, or `MX`
Record host	✓	The hostname Entri looks up (e.g. `_entri-verify`)
Expected value	✓	The value Entri expects to find at that host (e.g. `entri-verify=your-token`)

DNS lookup is the most reliable method when your nameservers aren’t fixed. Configure your platform to add the record above to every domain it manages.

Step 3 — Authentication

Decide how Entri logs into your API. You configure exactly one method per integration.

Method

Choose one of the three authentication methods:

Method	Description
OAuth 2.0	Recommended. The customer signs in to your dashboard to authorize Entri
Login (with optional MFA)	The customer enters their username + password directly in Entri
Basic Auth	An API key sent as the `Authorization` header. Simplest for read-only

OAuth credentials

Shown when OAuth 2.0 is selected. Find these in your OAuth app settings.

Field	Required	Description
Client ID	✓	The client ID for the Entri OAuth application registered in your system
Client secret	✓	The corresponding client secret — stored encrypted with AWS KMS
Authorization URL	✓	The OAuth authorization endpoint your users are redirected to
Token URL	✓	The token exchange endpoint
Scopes	—	Comma-separated OAuth scopes. Leave blank if your provider doesn’t use scopes
Entri redirect URI	(read-only)	Entri’s callback URI (e.g. `https://app.entri.com/auth/callback/<provider>`). Use Copy and add it to your OAuth app’s allowed callback URLs

With OAuth 2.0, Entri manages token injection automatically — you don’t need to declare Authentication Parameters. Once the customer approves access, Entri sends the access token as Authorization: Bearer <token> on every subsequent API call.

Authentication Parameters

Declare every value Entri injects into HTTP calls during authentication — the request field name, its location, and the static encrypted value Entri sends. Use Add parameter to open the drawer.

Field	Required	Description
Request Field Name	✓	The header, query, body field name, or URL variable for path segments (e.g. `X-API-Key`)
Location	✓	Where the value is placed: `header`, `query`, `body`, or `url`
Prefix	—	A string prepended to the value before injection (e.g. `Bearer` to produce `Authorization: Bearer <value>`)
Encrypted Value	✓	The fixed value — the same for every user, stored encrypted at rest (e.g. `encrypted:kms:arn:aws:kms:...`)

Authentication Parameters here carry static platform-level credentials (like an API key) that accompany every authentication call. OAuth 2.0 does not need them.

Request signing

Shown for Login and Basic Auth. Optional — configure this if you need to verify that signed requests originated from the Entri platform. Entri signs the request body with its global RSA private key; you verify using Entri’s public key.

Field	Description
Algorithm	Signing algorithm — `SHA256withRSA` (read-only)
Signature header	HTTP header where Entri attaches the base64-encoded signature (e.g. `Sig`, `X-Entri-Signature`)
Our public key ref (KMS ARN)	KMS ARN Entri uses to export its public key (`kms:GetPublicKey`). Share the resulting key material with your platform so it can verify signatures

Request signing is not applicable to OAuth 2.0.

Step 4 — DNS endpoints

Wire up your DNS API. Map each operation Entri needs to a route in your API. Complete every required row in the sidebar before you continue.

The sidebar lists the operations you must configure:

List domains

get_domains — Returns all domains for the authenticated customer. Entri calls this to populate the domain picker. The response should be a list of domains. Entri only reads the domain name from this response, so the single mapping you need is your domain name field to Entri’s name. If your API returns domainName, map domainName to name. Any other metadata in the payload (status, nameservers, expiration date, auto-renew, lock flags, and so on) is ignored. You do not need to map it, and you do not need to strip it out.

Read DNS records

get_records — Returns all DNS records for one domain. Entri calls this to read the current record state before making changes. Use {variableName} in the URL for the domain identifier returned by List domains. Map your record fields to Entri’s standard names in Field mappings if needed.

Record writes

Choose how your API creates and removes DNS records:

Separate — configure Add record (add_record) and Delete record (delete_record) as individual endpoints.
Batch — configure a single Batch DNS records (batch_records) endpoint that creates or updates multiple records in one call.

You only configure the rows for the shape you select. Both shapes are fully supported, and the choice does not change what Entri asks of your API beyond the endpoints themselves. See How Entri writes records for the exact sequence of calls in each mode.

Update nameservers

update_nameservers — Replaces the nameservers for a domain. Why Entri needs this. Not every connection is solved by writing DNS records. Some SaaS platforms run their own nameservers and take over the customer’s DNS zone entirely, pointing the domain at their nameservers so they can manage the zone themselves. Wix is one example. When a user connects a domain to a platform that works this way, the correct action is to delegate the domain rather than add records to your zone, which means Entri needs to be able to set the nameservers on the domain. Record management alone cannot cover those integrations. Address the domain by its name in the path, for example https://api.yourcompany.com/v1/domains/{domain}/nameservers where {domain} is the domain name. Nameserver updates do not have to complete synchronously. If your API accepts the change and processes it in the background, return 202 Accepted. Entri handles the asynchronous case and does not treat a 202 as a failure.

Add WWW redirect

add_www_redirect — Creates a www → root redirect (or root → www). Used when a user points their domain to an application and needs web forwarding. This endpoint is optional, but supporting it is strongly encouraged because many applications depend on www resolving. It is not the same as adding a www CNAME record: Entri expects a real HTTP 301 redirect, so this usually maps to your web forwarding feature rather than to your DNS record API.

Shared parameters

Values injected into every DNS endpoint call — sourced from the auth response or a static encrypted value. Use Add parameter to open the drawer.

Field	Required	Description
Request Field Name	✓	The header, query, body field name, or URL variable name for path segments
Location	✓	Where the value is placed: `header`, `query`, `body`, or `url`
Prefix	—	A string prepended to the value before injection
Source	✓	`auth` — extracted from the token/auth response via a JSON path. `static` — a fixed encrypted value, the same for every user
JSON Path	✓ (if `source: auth`)	JSONPath to extract from the authentication response (e.g. `$.accessToken`)
Static Value	✓ (if `source: static`)	The fixed value, stored encrypted — the same for every user

How Entri writes records

Conflict detection and resolution happen entirely on Entri’s side, before any write endpoint is called. You do not implement conflict logic, and your write endpoints do not need to inspect the existing zone. Every DNS change follows the same sequence:

Entri calls your get_records endpoint to fetch the current records on the domain.
Entri runs an internal analysis comparing the existing records against the records that need to be added, and identifies conflicts, meaning existing records that would clash with a new one.
Entri writes the resolved changes using whichever write endpoints you exposed.

How step 3 is carried out depends on the record write shape you configured:

Write shape	What Entri sends
Batch (`batch_records`)	Entri computes the final desired state, which is the existing records minus the conflicting ones plus the new records, and sends it as a single request containing the full merged zone. Your API applies the set as given.
Separate (`add_record` + `delete_record`)	Entri first sends delete requests for the conflicting records, then sends add requests for the new records.

In batch mode the payload is the complete zone after merging, not a diff of the customer’s changes. Your endpoint should treat the request as the authoritative record set for that domain.

Both shapes are equally valid. Expose either a batch endpoint or the add and delete pair, and Entri adapts its write strategy to what you support.

API behavior and compatibility

Entri is designed to work with your API as it already exists. A few common questions about what Entri tolerates: Internationalized domain names. Entri handles both Punycode and Unicode. If your endpoints return blog.xn--mnchen-3ya.de, that is fine, and so is blog.münchen.de. No normalization is needed on your side. Concurrent edits. Entri does not require optimistic locking or version checking, and does not depend on a 409 Conflict response when two clients write to the same zone at once. Because Entri reads the zone immediately before writing, the window for a collision is very small. If you already implement version checking, keeping it causes no problems. Asynchronous operations. A 202 Accepted response is handled correctly, which matters most for nameserver updates on TLDs that process changes in the background. Error responses. Entri reads the error message from the JSON path you configure as Error Path, and accepts either a single string or an array of strings at that path. See Response Mapping. Pagination metadata. Not required. See Pagination.

Endpoint configuration

Every DNS endpoint is described using the same set of fields.

HTTP Request

Field	Required	Description
Method	✓	HTTP method. Read endpoints (`get_domains`, `get_records`) are `GET`; write endpoints offer `POST`, `PUT`, `PATCH`, and (where valid) `DELETE`
API URL	✓	Full API URL. Use `{variableName}` for path variables — e.g. `https://api.yourcompany.com/v1/domains/{domainId}/records`
Static Query Parameters	—	Fixed query parameters appended to every request. Pagination parameters are managed automatically — don’t add them here
Request Headers	—	Headers added to every call. `Authorization` is injected automatically from your auth parameters

Request Body

Shown for non-GET methods. JSON only. Use {{variableName}} for template variables — values from the domain detection step or auth response are injected at call time. For example:

{ "name": "{{host}}", "type": "A" }

Response Mapping

For read endpoints (get_domains, get_records), tell Entri how to read your API’s response:

Field	Required	Description
Data Path	✓	JSONPath to the list/array in your response — e.g. `$.records`, `$.data.items`, or `$` if the response is the array itself
Error Path	✓	JSONPath to the error message in failed responses (e.g. `$.error.message`)

For mutation endpoints (add_record, delete_record, batch_records, update_nameservers, add_www_redirect), only Error Path is shown.

Error Path can point at either a string or an array of strings. Some APIs return an error message that is a single string in some cases and an array of messages in others. Both shapes are supported, so you do not need to normalize the field before returning it.

Field mappings

Field mappings are optional. They exist only to translate names, so you need an entry only when a field in your API has a different name than the one Entri expects. If your API already uses Entri’s names, leave the mappings empty. Open the dropdown next to any mapping row to see the full list of names Entri recognizes. For DNS records, these are the only fields Entri needs:

Entri field	Description
`host`	The record hostname or subdomain
`value`	The record value
`ttl`	Time to live, in seconds
`priority`	Priority, for record types that use it (such as MX)

Example, if your API returns content instead of value:

Your field	Entri standard
`content`	`value`

The dropdown also lists type, name, id, and the type-specific names for SRV, MX, and CAA records (srv.priority, srv.weight, srv.port, srv.target, mx.priority, mx.host, caa.flag, caa.tag, caa.value). Map those only if your API names them differently.

The `id` field

Entri does not require a record id, in either batch or separate write mode. Map it only when your own endpoints need it. For example, if your delete_record route addresses records by ID, Entri has to know which field carries that ID, so map it. If your API identifies records by host, type, and value instead, no id mapping is needed and your records do not need an ID field at all.

Pagination

If get_domains or get_records returns paginated results, configure pagination so Entri fetches all pages automatically. Choose one of: none, page_based, cursor_based, or offset_based, then fill in the parameter names for that style. Entri only needs the request parameters, such as page and limit. Response metadata like total_count or current_page is not required, and Entri paginates correctly without it.

Pagination parameters (page number, cursor, offset) are managed automatically by Entri. Do not add them as Static Query Parameters.

Testing your integration

Entri does not host an external staging or sandbox environment for the network integration, and there is currently no self-serve tool that lets you run the full connection flow against your own configuration to verify it. That capability is on the roadmap but is not available yet. Testing happens through the draft and review process instead. Your configuration is a draft by default. Nothing you enter is live, and you can edit every step as many times as you need. When the configuration looks right, you submit it for review. Entri’s team then runs the full end-to-end experience against your API, including the authentication flow and every configured endpoint, and reports any findings back to you. Nothing is published until it passes. So once you have finished wiring up authentication and your endpoints, submitting for review is the way to confirm the integration works. You do not need to validate it yourself first. Configure your integration against your production environment. Entri’s review tests the real flow on real domains, so production endpoints and production credentials are what we expect to see, and they are required before your integration goes live.

If your platform cannot be reviewed against production for some reason, contact Entri before you submit. Staging configurations are handled case by case, not as a standard step. Domain detection depends on public DNS, so nameserver match and DNS lookup cannot be verified against test domains that do not resolve publicly.

Step 5 — Review & submit

Final check. Take one more look. When you submit, Entri’s team reviews your integration and flips you live in the network — usually within one business day.

The review screen summarizes everything you’ve configured, grouped into blocks:

Provider — name, website, support email, logo, brand color.
Authentication — method, OAuth credentials (if applicable), static auth parameters, and request-signing settings.
Domain detection — the approach, your nameservers, and the DNS record check.
DNS endpoints — the method and URL for each configured operation.

If any step is incomplete, the screen lists exactly what’s left to finish before you can submit. When everything is complete, choose Submit for review. After submission, the Entri team reviews and tests your configuration — you won’t be able to make edits while it’s in review. If your configuration passes, Entri publishes it into the Entri Connect modal and notifies you by email.

You cannot submit until every required field across all steps is complete.

Submission checklist

Before submitting your integration, verify the following are configured:

Provider profile — provider name and support email
Domain detection — at least one method (nameserver match and/or DNS lookup)
Authentication — one method (OAuth 2.0, Login, or Basic Auth) and its required fields
DNS endpoints
- List domains (get_domains)
- Read DNS records (get_records)
- Record writes — either Add record + Delete record, or Batch DNS records
- Update nameservers
- Add WWW redirect (optional, recommended)

Field mappings are only needed where your field names differ from Entri’s, so an empty mapping list is not a blocker.

​Overview

​Step 1 — Provider profile

​Brand

​Manual fallback

​Preview

​Step 2 — Domain detection

​Nameserver match

​DNS lookup (recommended)

​Step 3 — Authentication

​Method

​OAuth credentials

​Authentication Parameters

​Request signing

​Step 4 — DNS endpoints

​List domains

​Read DNS records

​Record writes

​Update nameservers

​Add WWW redirect

​Shared parameters

​How Entri writes records

​API behavior and compatibility

​Endpoint configuration

​HTTP Request

​Request Body

​Response Mapping

​Field mappings

​The id field

​Pagination

​Testing your integration

​Step 5 — Review & submit

​Submission checklist

Overview

Step 1 — Provider profile

Brand

Manual fallback

Preview

Step 2 — Domain detection

Nameserver match

DNS lookup (recommended)

Step 3 — Authentication

Method

OAuth credentials

Authentication Parameters

Request signing

Step 4 — DNS endpoints

List domains

Read DNS records

Record writes

Update nameservers

Add WWW redirect

Shared parameters

How Entri writes records

API behavior and compatibility

Endpoint configuration

HTTP Request

Request Body

Response Mapping

Field mappings

The `id` field

Pagination

Testing your integration

Step 5 — Review & submit

Submission checklist