Connect Configuration

`entri.connectDomain(config)`

This method launches the Entri modal window. config is an object with the following properties:

Property	Type	Required?	Default	Description
applicationId	string	Yes	N/A	The ID of your application (set in the dashboard)
dnsRecords	array of DNSRecord objects (see below)	Yes	N/A	The DNS records you wish to configure for your users (see below)
token	string	Yes	N/A	A JSON web token. Must be fetched in each session, see Token creation (JWT).
applicationUrl	string	Only when using Secure or Power	N/A	Sets the applicationUrl for Power. This is the specific application URL that you would like to render on the customer’s custom domain. Also known as an origin server or origin URL.
applicationName	string	No	null	The company name that will be shown in the initial screen’s welcome message.
defaultSubdomain	string	No	""	If you would like to pre fill the subdomain field with text then enter the desired sub domain here.
enableDkim	boolean	No	false	If your application requires users to set up DKIM through their email provider (and your app does not send emails directly), enable this. This is common for applications that provide email automation using an external service like Google Workspace or Microsoft 365. (Enterprise tier)
forceManualSetup	boolean	No	false	Forces Entri to use the manual setup flow. If set to true then the prefilledDomain becomes required.
forceSubdomain	boolean	No	false	If your application requires subdomains, enable this. (Premium and Enterprise tiers)
locale	string	No	en	To load Entri in a specific language. Supported languages include: en, es, pt, pt-br,pt-pt, fr, it, de, nl, pl, tr, ja, da, sv.The pt locale defaults to Brazilian portuguese (pt-br).
hostRequired	boolean	No, unless you use the `{SUBDOMAIN}` variable	true	If the `{SUBDOMAIN}` variable is used but is null (no subdomain inputted by the user) then the `{SUBDOMAIN}` value will default to be www. See Dynamic configuration variables based on the user-inputted domain.
manualSetupDocumentation	string	No	""	Where you currently provide documentation on how to set up DNS. If users are trying to set up their DNS manually and need help, we will send them to this page. e.g. <https://example.com/dns-setup\>. This link is disabled when using the propertydisableManualSetupDocumentationLink:true in the whiteLabel’s configuration.
iframeSandbox	boolean	No	false	When set to `true`, applies a `sandbox` attribute to the Entri iframe, restricting its capabilities to only: `allow-scripts`, `allow-same-origin`, `allow-forms`, `allow-popups`, and `allow-popups-to-escape-sandbox`. This adds an extra layer of security to the embedded iframe.
overrideSPF	boolean	No	false	Forces the SPF record override in case there is a pre-existent one instead of merging it. This feature is not supported by Cloudflare, IONOS, Squarespace, and GoDaddy providers.
power	boolean	No	false	Enables Entri Power. Requires adoption of Entri Power.
prefilledDomain	string	No, unless forceManualSetup is set to true	N/A	A domain to pre-fill if you’ve collected it before the Entri modal, e.g. example.com
secureRootDomain	boolean	No	false	Creates a certificate for the root domain and points its A records to Entri secure servers. Requires adoption of Entri Secure.
supportForSubdomains	boolean	No	true	If your application allows subdomains, enable this
userId	string	No	N/A	A unique ID so that you can match Entri webhook events to the user. You can use stringfied jsons in order to add complex structured data.
wwwRedirect	boolean	No	false	When feasible, Entri will automatically redirect site.com to www.site.com using the preferred method of the DNS provider. Certain providers prevent Entri from automatically setting this up. When that is the case, Entri shows a helper UI to the user that explains how to do this manually.
validateDmarc	boolean	No	false	When set to `true` Entri will automatically check if there is an existing and valid DMARC record. If so, Entri will not update the DMARC record.
validateCAA	boolean	No	false	When set to `true` Entri will check if there is an existing CAA present in the domain or not. If it is present, it will add the CAA record sent in the config, else not.
checkConflicts	boolean	No	false	When `true`, Entri analyzes the DNS records provided in `dnsRecords` against the existing authoritative DNS configuration and reports any record that would require an override. Increases response time. See Detecting Record Conflicts.
monitor	boolean	No	false	When `true`, automatically registers the configured domain and records with Entri Monitor after the Connect flow completes, so record drift is reported back via webhooks. Requires a Monitor-enabled plan.
searchType	string	No	`"classic"`	(Entri Sell, IONOS only) Selects the domain-search experience. Use `"classic"` for the standard keyword search, or `"ai"` to enable AI-generated domain suggestions.

Possible `connectDomain()` Errors

When any of the following critical errors occur, a console error will be logged, and the user will only see “Entri is misconfigured. Please contact support for assistance.” in the UI.

Error	Console Message	Reason
Domain Invalid or Unsupported TLD	”This domain is invalid or uses an unsupported TLD (unlisted ).”	The domain provided doesn’t pass validation (invalid TLD, not in ICANN list, or malformed).
Missing applicationId	”Missing parameter: applicationId”	The configuration object does not include `applicationId`.
Configuration Error	”Configuration error, please refer to the docs at https://developers.goentri.com/docs”	`forceManualSetup: true` was used without providing `prefilledDomain`.

Token creation (JWT)

To launch the Entri modal window in a session, you’ll need to fetch a JWT using the secret key and applicationId provided by the Entri dashboard. For security reasons and in order to not expose your secret in the browser, please make sure to fetch the JWT on the server-side of your application. The JWT expires after 60 minutes. You can use any networking library you’d like. Here’s an example using javascript:

fetch('https://api.goentri.com/token', {
  method: 'POST',
  body: JSON.stringify({
    // These values come from the Entri dashboard
    applicationId: "12345",
    secret: "12345-67890"
  }),
})
.then(response => response.json())
.then(data => {
  console.log('Success:', data); // { "auth_token": "exampletoken..." }
})
.catch((error) => {
  console.error('Error:', error);
});

Enhancing Integration Security

To further enhance the security of your integration, you have the option to include the domain, dnsRecords or product in the JWT creation process. When these elements are added, Entri will validate them during execution, providing an additional layer of security.

POST https://api.goentri.com/token

Request body

JSON

{
    "applicationId": "{APPLICATION_ID}",
    "secret": "{SECRET}",
    "domain": "sampledomain.com",
    "freeDomain": true,
    "userId": "XYZ",
    "product": "connect",
    "dnsRecords": [
        {
            "value": "samplevalue.com",
            "host": "@",
            "ttl": 300,
            "type": "CNAME"
        }
    ]
}

Parameters description

Parameter	Required?	Default	Description
applicationId	Yes	N/A	The ID of your application (set in the dashboard)
domain	Yes	N/A	The domain that will be configured
secret	Yes	N/A	Client secret, can be found in the Dashboard
dnsRecords	No	N/A	Records that will be configured on the `domain`
freeDomain	No	N/A	Only applies to Entri Sell! Specifies a free or paid domain purchase.
product	No	N/A	The Entri product this JWT is being created for. Accepted values: `connect`, `sell`, `power`, `secure`, `monitor`. Required by the endpoints listed under Endpoints that require a product claim.
userId	No	N/A	The `userId` from the user that will be using the flow.

Successful response (200 status)

JSON

{ "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." }

For more details about how freeDomain is used in Entri Sell, refer to the Advanced Security Settings for freeDomain section.

Endpoints that require a product claim

When a JWT carries a product value, Entri only accepts it on the endpoints of that product. A token issued for sell, for example, is rejected with a 403 and the message JWT is not valid for this resource on Power or Secure endpoints. The server-side endpoints that list every domain of an application go one step further and require the matching product claim. A token without it is rejected with a 403 and the message The token must be issued with product '<product>' to use this endpoint, and no domains are returned. This applies even to applications that have authentication disabled.

Endpoint	Required `product`
`GET /power` without `domain`	`power`
`GET /ssl` without `domain`	`secure`
`GET /sell/domains`	`sell`
`GET /monitor/domains`	`monitor`
`POST /monitor/domains/batch`	`monitor`
`DELETE /monitor/domains/batch`	`monitor`
`GET /monitor/domains/batch/status/:request_id`	`monitor`

Endpoints that act on a single domain, such as the Power and Secure eligibility checks with ?domain= or the Monitor endpoints for one domain, keep working with a token that has no product claim. On Monitor, the domain and dnsRecords claims are also enforced on every single-domain endpoint. See Token scope for the rules.

Get Started

Activate Suite

Domain Management

SSL Provisioning

For DNS Providers

DNS Concepts

Entri MCP

Reference

Legal & Security

Resources

Connect Configuration

`entri.connectDomain(config)`

Possible `connectDomain()` Errors

Token creation (JWT)

Enhancing Integration Security

Request body

Parameters description

Successful response (200 status)

Endpoints that require a product claim

​entri.connectDomain(config)

​Possible connectDomain() Errors

​Token creation (JWT)

​Enhancing Integration Security

​Request body

​Parameters description

​Successful response (200 status)

​Endpoints that require a product claim

`entri.connectDomain(config)`

Possible `connectDomain()` Errors

Token creation (JWT)

Enhancing Integration Security

Request body

Parameters description

Successful response (200 status)

Endpoints that require a product claim