API Reference
entri.showEntri(config)
entri.showEntri(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) |
token | string | Yes | N/A | A JSON web token. Must be fetched in each session, see Installation. |
dnsRecords | array of DNSRecord objects (see below) | Yes | N/A | The DNS records you wish to configure for your users (see below) |
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 |
userId | string | No | N/A | A unique ID so that you can match Entri webhook events to the user |
supportForSubdomains | boolean | No | true | If your application allows subdomains, enable this |
forceSubdomain | boolean | No | false | If your application requires subdomains, enable this |
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/docs/dns-setup > |
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. |
defaultSubdomain | string | No | "" | If you would like to pre fill the subdomain field with text then enter the desired sub domain here. |
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. |
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. |
locale | string | No | en | To load Entri in a specific language. Supported languages include: en , es , pt , fr , it , de , nl , pl , tr , ja |
forceManualSetup | boolean | No | false | Forces Entri to use the manual setup flow. If set to true then the prefilledDomain becomes required. |
applicationUrl | string | Only when using 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. |
power | boolean | No | false | Enables Entri Power. |
DNSRecord object
DNS records can have the following properties:
Property | Type | Required? | Example |
---|---|---|---|
type | string (see below) | Yes | CNAME |
host | string | Yes | www |
value | string | Yes | m.example.com |
ttl | integer | Yes | 300 |
priority | integer | Only for MX records | 10 |
fallbackValue | string | No | v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDg9/gR+3J0mmugLjhpYOfQK9ytkEKnXM0kVdpu0UoykSPK7ChD+nRxFJbN2cxtvu8GrCNQwPTKbC0jimaSi0V2j3JndnRrECuYCqeZYcRmw2lYs18QnmJRfCpweKoaGtv9zERCkeHwLcTaLkrSHrRDf58WgERg8x/4ipBPIyZufwIDAQAB |
onEntriClose
Callback Event Data:lastStatus
fields
onEntriClose
Callback Event Data:lastStatus
fieldsThese are the following potential values for lastStatus
returned as part of the onEntriClose
callback event.
lastStatus | Description |
---|---|
FINISHED_SUCCESSFULLY | The user has successfully configured their domain using the automatic flow. |
IN_PROGRESS | The user exited the Entri modal while the DNS setup was in progress. |
EXISTING_RECORDS | The user exited the Entri modal when prompted if they want to override an existing set of DNS records. |
LOGIN | The user exited the Entri modal flow during the login process (when prompted for their login credentials and/or 2FA verification) |
MANUAL_CONFIGURATION | The user exited the Entri modal after manual DNS configuration instructions were presented. |
EXIT_WITH_ERROR | The user exited the Entri modal after an error occurred. |
DKIM_SETUP | The user exited the Entri modal after prompting |
Supported Record Types
Type | Description |
---|---|
A | Holds the IP address of a domain. |
AAAA | The AAAA record is conceptually similar to the A record, but it allows you to specify the IPv6 address of the server, rather than the IPv4. |
CNAME | Forwards one domain or subdomain to another domain. Does not provide an IP address. |
CAA | Used to provide additional confirmation for the Certification Authority (CA) when validating an SSL certificate. |
MX | Directs email to an email server. |
TXT | Stores text strings. For special uses of the TXT record, see Handling DKIM, SPF, and DMARC records. |
NS | Indicates which DNS server is authoritative for that domain, it is the server that stores all DNS records for a domain, including A records, MX records, or CNAME records. |
entri.checkDomain(domain, config)
entri.checkDomain(domain, config)
This asynchronous method checks if Entri supports automatic setup for a particular domain. It accepts two arguments:
Argument | Type | Example |
---|---|---|
domain | string - a domain with no subdomain | example.com |
config | Entri configuration object | See above |
Webhooks
Entri sends JSON data via webhook to notify your backend when events occur. For example:
{
"id": "028b5078-8fed-4ffb-8e3e-3e6e6d8214b4",
"user_id": "sample-user",
"domain": "smallbusiness.com",
"type": "domain.added",
"propagation_status": "success",
"dkim_status": "success",
"redirection_status": "exempt",
"ssl_status": "success",
"data": {
"records_propagated": [
{
"type": "A",
"host": "smallbusiness.com",
"value": "54.153.2.220"
},
{
"type": "CNAME",
"host": "www",
"value": "smallbusiness.com"
}
],
"records_non_propagated": [],
"updated_objects": [
"propagation_status",
"ssl_status"
]
}
}
The JSON object contains the following properties:
Property | Type | Description |
---|---|---|
id | string | Entri's ID for the webhook event |
user_id | string | The user ID that your application can optionally send via the configuration object during setup (see the entri.showEntri method) |
domain | string | The domain name set by your user |
type | string | The event type. Options: - domain.added - domain.timeout |
propagation_status | string | The DNS propagation status. Options: - success - pending - failure |
dkim_status | string | Whether DKIM has been set up (see Handling DKIM, SPF, and DMARC Records). Options: - success - pending - failure - exempt (the feature is disabled) |
redirection_status | string | If the wwwRedirect feature was enabled for your applicationId, then Entri will check to confirm the status of the url redirect. Options: - success - pending - failure - exempt (the feature is disabled) |
ssl_status | string | Whether an SSL certificate has been provisioned (see Provisioning SSL Certificates). Options: - success - pending - failure - exempt (the feature is disabled) |
data.records_propagated | array of DNSRecord objects | See above |
data.records_non_propagated | array of DNSRecord objects | See above |
updated_objects | array of strings | The object properties that have been updated since the last webhook event. |
Secure - SSL certificates
Check the status of a domain
GET https://api.goentri.com/ssl?domain=www.example.com
Successful response (200 status)
{
// Is the domain CNAMEed to the cname_target of the application?
"eligible": true | false,
// Is SSL provisioned?
"sslStatus": "active" | "inactive"
}
Possible error responses
Errors are returned as a {message: 'string'}
object.
Error message | Status |
---|---|
Domain provided couldn't be resolved. | 400 |
Internal Server Error. | 502 |
Provision an SSL certificate
POST https://api.goentri.com/ssl
Request body
{ "domain": "www.example.com" }
Successful response (200 status)
{ "message": "Success." }
Possible error responses
Errors are returned as a {message: 'string'}
object.
Error message | Status |
---|---|
There is already a valid certificate for this domain. | 502 |
Please review SSL eligibility status of this product. | 502 |
Please complete step 1. | 502 |
Internal Server Error. | 502 |
Renew an SSL certificate
PUT https://api.goentri.com/ssl
Request body
{ "domain": "www.example.com" }
Successful response (200 status)
{ "message": "Success." }
Possible error responses
Errors are returned as a {message: 'string'}
object.
Error message | Status |
---|---|
{detailed error message when renewing the domain} | 502 |
Deprovision an SSL certificate
DELETE https://api.goentri.com/ssl
Request body
{ "domain": "www.example.com" }
Successful response (200 status)
{ "message": "Success." }
Possible error responses
Errors are returned as a {message: 'string'}
object.
Error message | Status |
---|---|
Domain not valid | 502 |
{detailed error message when deleting the SSL certificate of the domain} | 502 |
Updated 13 days ago