Check the SSL delegation record now
const url = 'https://api.nsin.ir/domains/example.com/ssl/delegation/check';const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.nsin.ir/domains/example.com/ssl/delegation/check \ --header 'Authorization: Bearer <token>'Runs a live check of the ssl_delegation CNAME of an external-DNS
domain — the record that lets NSIN issue and renew its certificate
automatically — and records the result on the domain. A passing check
on a domain still awaiting verification also activates it: the record
proves control of the domain’s DNS exactly as the TXT record does.
The check queries TXT _acme-challenge.{domain} through public
resolvers and looks for this domain’s own canary value, so it tests
what a certificate authority will see end to end. Rate limited to once
a minute per domain, shared with verify. Requires ssl.manage.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The domain name (for example example.com) — not a numeric id.
Example
example.comResponses
Section titled “ Responses ”The delegation is in place. Issuance proceeds automatically.
object
Present when ok is false.
An external-DNS domain’s verification record: one CNAME, created once
and never rotated. It proves ownership (a pending domain activates when
it is found) and stays in place afterwards as the domain’s connection
to NSIN, which is what lets NSIN issue and renew the certificate for the
apex and its wildcard. Once it has passed, removing or changing it
marks the domain moved — it keeps serving for a 3-day grace period,
then is disabled — exactly as a managed domain whose nameservers leave.
object
Name to create the CNAME at
The CNAME target
Whether the last live check found this domain’s delegation in place.
When the last check ran.
When the delegation last passed.
Why the last check failed — or, with ok true, a CAA policy on the
domain that prevents Let’s Encrypt from issuing.
How often NSIN re-checks the record on its own.
object
pending— managed domain waiting for its nameservers to point at NSIN.unverified— external-DNS domain waiting for its verification record.active— serving.moved— delegation has left NSIN; the domain keeps serving during a grace window.disabled— not serving; re-enable withPOST /domains/{domain}/enable.banned— administratively blocked.
managed — NSIN hosts the DNS zone. external — you host DNS
elsewhere and prove ownership with a TXT record.
Id of the owning user.
Per-domain cap on disk (L2) cache size, in GB.
How long a disk-cache entry may live, in days. Maximum 7.
Largest response body NSIN will buffer and cache, in MB. Bigger responses stream straight from origin and are never cached. The selectable ceiling depends on the domain’s plan.
While set and in the future, the edge bypasses cache reads and writes for this domain. Absent when developer mode is off.
When the background nameserver checker will next look at this domain.
Last user-triggered nameserver check; these are limited to one per hour.
Send X-Content-Type-Options: nosniff. Off by default — it can break
an origin that mislabels asset MIME types.
Send Referrer-Policy: strict-origin-when-cross-origin.
Strip origin fingerprint headers from responses.
Send Strict-Transport-Security, telling browsers to use HTTPS only
for this domain. Off by default.
This one cannot be undone. A browser that has seen the header
refuses plain HTTP for the whole hsts_max_age_sec even after the
header stops being sent; switching it off only stops new visitors
from being pinned. Enable it only when every path on the domain
works over HTTPS. The edge’s value replaces an origin’s own
Strict-Transport-Security header (a browser reads only the first
one it receives).
How long browsers keep enforcing HTTPS, in seconds. 0 is
“never set”. Only the listed values are accepted, and this API
raises it one step at a time — from 0 the only allowed next
value is 300, then 3600, and so on. Lowering it is always allowed
and is the way back out. The edge treats anything under 300 as off.
Add includeSubDomains, applying the rule to every subdomain,
including ones created later. A subdomain not served over HTTPS
becomes unreachable for visitors who have seen the header.
Add the preload directive, the prerequisite for submitting the
domain at hstspreload.org. Requires hsts_enabled,
hsts_include_subdomains and hsts_max_age_sec of 31536000.
Effectively permanent: getting off the browser preload list means asking hstspreload.org to delist the domain and waiting for people to update their browsers. If a precondition is later removed, this flag is cleared with it.
Lowest TLS version a visitor may connect with. 1.2 (default)
accepts TLS 1.2 and 1.3; 1.3 refuses TLS 1.2 handshakes. Nothing
below 1.2 is offered on any domain. It is enforced during the TLS
handshake from the SNI, so a client below the minimum gets a
connection error rather than an HTTP response. HTTP/3 is TLS 1.3 by
definition and is unaffected.
Serve a Markdown rendering of eligible HTML pages to clients sending
Accept: text/markdown. Requires an active plan.
HTTP version the edge speaks to this domain’s origins on the direct
path. Default http1, and deliberately so: over HTTP/2 an upload is
limited by the origin’s per-stream window (64 KB on nginx), which
caps each upload near 4 MB/s at a 16 ms edge-to-origin round trip.
http3 falls back to TCP per origin when the QUIC dial fails. The
tunnel path from Iranian edges to foreign origins is always HTTP/1.1.
Probe what your origin supports with GET /domains/{domain}/origin-protocols.
Cache static files (CSS, JavaScript, images, fonts, media, downloads)
at the edge automatically, even with no cache rule — the way
Cloudflare does for every proxied hostname. On by default. HTML is
never cached by this; your own cache rules always take precedence,
and any path you exclude in a rule is never cached by the default.
Freshness follows your origin’s Cache-Control; with none, 5 minutes.
Bot cache: keep an edge copy of every HTML page for verified
search-engine crawlers (Googlebot, Bingbot, Applebot, DuckDuckBot,
YandexBot) and serve them from it, regardless of the origin’s
Cache-Control. Human visitors are unaffected. A crawler must pass
the operator’s own verification (published IP ranges / reverse DNS);
a spoofed User-Agent never gets the copy. Requires a plan with
bot_cache_enabled; the edge switches it off automatically while
the plan lacks it.
Bot cache: seconds a copy is served without asking the origin (300–86400, default 3600). Older copies are still served and refreshed in the background with a conditional request.
Bot cache: seconds after which a copy is no longer served and is fetched again (300–86400, default 86400).
Crawlers the bot cache serves. Empty means all of them.
Wildcard path patterns (/api/*) never served from the bot cache.
Notify the owner when a subdomain suffers a sustained origin outage.
Per-minute origin-error percentage that counts as “down”.
Minutes the domain must stay down before an incident opens.
Minimum origin-eligible requests in the window — the traffic floor below which no incident opens.
Minimum populated one-minute buckets required in the window.
Consecutive clear minutes before an incident resolves.
Paused for billing. The edge refuses the domain’s TLS handshake, so visitors get a connection error. Clears automatically once the wallet is no longer negative.
The legacy TXT record that proves ownership of an external-DNS domain.
Still accepted, but new domains verify with the CNAME in
ssl_delegation, which also keeps their certificate renewing — prefer
that one.
object
Name to create the TXT record at.
Exact TXT value to publish.
An external-DNS domain’s verification record: one CNAME, created once
and never rotated. It proves ownership (a pending domain activates when
it is found) and stays in place afterwards as the domain’s connection
to NSIN, which is what lets NSIN issue and renew the certificate for the
apex and its wildcard. Once it has passed, removing or changing it
marks the domain moved — it keeps serving for a 3-day grace period,
then is disabled — exactly as a managed domain whose nameservers leave.
object
Name to create the CNAME at
The CNAME target
Whether the last live check found this domain’s delegation in place.
When the last check ran.
When the delegation last passed.
Why the last check failed — or, with ok true, a CAA policy on the
domain that prevents Let’s Encrypt from issuing.
How often NSIN re-checks the record on its own.
The canonical (first) accepted nameserver set.
Every accepted nameserver set. The delegation must match exactly one set in full — sets cannot be mixed.
The nameservers currently observed in the parent zone.
Your role on a domain. owner is implicit for the domain’s creator and
for global admins; the other three are grantable via sharing.
How often the background checker re-checks the delegation.
Whose wallet this domain’s charges come out of. Always present —
it falls back to the owner — so a client can name the payer
without a second request. Change it with
PUT /domains/{domain}/billing-member.
object
Who made the nomination. Absent when the owner pays.
True when no nomination is in force and the domain owner pays. The owner being named explicitly is stored as no nomination, so this never disagrees with ownership.
Example
{ "ssl_delegation": { "type": "CNAME" }, "domain": { "name": "example.com", "status": "pending", "dns_mode": "managed", "cache_cap_mb": 128, "hsts_max_age_sec": 0, "min_tls_version": "1.2", "origin_protocol": "http1", "bot_cache_kinds": [ "googlebot" ], "verification": { "type": "TXT" }, "ssl_delegation": { "type": "CNAME" }, "my_role": "owner", "my_permissions": [ "domain.view" ] }}Not an external-DNS domain, or the domain is disabled or banned.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Example
{ "error": "read-only API key"}Missing, malformed, revoked or expired API key — or the owning account is inactive.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "invalid API key"}The key is read-only, your role on the domain lacks the required permission, or the domain’s plan does not include the feature.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Example
{ "error": "read-only API key"}No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Example
{ "error": "read-only API key"}The record was not found, has not propagated, or points at a
delegation that does not belong to this domain. ok is false and
error says what was seen.
object
Present when ok is false.
An external-DNS domain’s verification record: one CNAME, created once
and never rotated. It proves ownership (a pending domain activates when
it is found) and stays in place afterwards as the domain’s connection
to NSIN, which is what lets NSIN issue and renew the certificate for the
apex and its wildcard. Once it has passed, removing or changing it
marks the domain moved — it keeps serving for a 3-day grace period,
then is disabled — exactly as a managed domain whose nameservers leave.
object
Name to create the CNAME at
The CNAME target
Whether the last live check found this domain’s delegation in place.
When the last check ran.
When the delegation last passed.
Why the last check failed — or, with ok true, a CAA policy on the
domain that prevents Let’s Encrypt from issuing.
How often NSIN re-checks the record on its own.
object
pending— managed domain waiting for its nameservers to point at NSIN.unverified— external-DNS domain waiting for its verification record.active— serving.moved— delegation has left NSIN; the domain keeps serving during a grace window.disabled— not serving; re-enable withPOST /domains/{domain}/enable.banned— administratively blocked.
managed — NSIN hosts the DNS zone. external — you host DNS
elsewhere and prove ownership with a TXT record.
Id of the owning user.
Per-domain cap on disk (L2) cache size, in GB.
How long a disk-cache entry may live, in days. Maximum 7.
Largest response body NSIN will buffer and cache, in MB. Bigger responses stream straight from origin and are never cached. The selectable ceiling depends on the domain’s plan.
While set and in the future, the edge bypasses cache reads and writes for this domain. Absent when developer mode is off.
When the background nameserver checker will next look at this domain.
Last user-triggered nameserver check; these are limited to one per hour.
Send X-Content-Type-Options: nosniff. Off by default — it can break
an origin that mislabels asset MIME types.
Send Referrer-Policy: strict-origin-when-cross-origin.
Strip origin fingerprint headers from responses.
Send Strict-Transport-Security, telling browsers to use HTTPS only
for this domain. Off by default.
This one cannot be undone. A browser that has seen the header
refuses plain HTTP for the whole hsts_max_age_sec even after the
header stops being sent; switching it off only stops new visitors
from being pinned. Enable it only when every path on the domain
works over HTTPS. The edge’s value replaces an origin’s own
Strict-Transport-Security header (a browser reads only the first
one it receives).
How long browsers keep enforcing HTTPS, in seconds. 0 is
“never set”. Only the listed values are accepted, and this API
raises it one step at a time — from 0 the only allowed next
value is 300, then 3600, and so on. Lowering it is always allowed
and is the way back out. The edge treats anything under 300 as off.
Add includeSubDomains, applying the rule to every subdomain,
including ones created later. A subdomain not served over HTTPS
becomes unreachable for visitors who have seen the header.
Add the preload directive, the prerequisite for submitting the
domain at hstspreload.org. Requires hsts_enabled,
hsts_include_subdomains and hsts_max_age_sec of 31536000.
Effectively permanent: getting off the browser preload list means asking hstspreload.org to delist the domain and waiting for people to update their browsers. If a precondition is later removed, this flag is cleared with it.
Lowest TLS version a visitor may connect with. 1.2 (default)
accepts TLS 1.2 and 1.3; 1.3 refuses TLS 1.2 handshakes. Nothing
below 1.2 is offered on any domain. It is enforced during the TLS
handshake from the SNI, so a client below the minimum gets a
connection error rather than an HTTP response. HTTP/3 is TLS 1.3 by
definition and is unaffected.
Serve a Markdown rendering of eligible HTML pages to clients sending
Accept: text/markdown. Requires an active plan.
HTTP version the edge speaks to this domain’s origins on the direct
path. Default http1, and deliberately so: over HTTP/2 an upload is
limited by the origin’s per-stream window (64 KB on nginx), which
caps each upload near 4 MB/s at a 16 ms edge-to-origin round trip.
http3 falls back to TCP per origin when the QUIC dial fails. The
tunnel path from Iranian edges to foreign origins is always HTTP/1.1.
Probe what your origin supports with GET /domains/{domain}/origin-protocols.
Cache static files (CSS, JavaScript, images, fonts, media, downloads)
at the edge automatically, even with no cache rule — the way
Cloudflare does for every proxied hostname. On by default. HTML is
never cached by this; your own cache rules always take precedence,
and any path you exclude in a rule is never cached by the default.
Freshness follows your origin’s Cache-Control; with none, 5 minutes.
Bot cache: keep an edge copy of every HTML page for verified
search-engine crawlers (Googlebot, Bingbot, Applebot, DuckDuckBot,
YandexBot) and serve them from it, regardless of the origin’s
Cache-Control. Human visitors are unaffected. A crawler must pass
the operator’s own verification (published IP ranges / reverse DNS);
a spoofed User-Agent never gets the copy. Requires a plan with
bot_cache_enabled; the edge switches it off automatically while
the plan lacks it.
Bot cache: seconds a copy is served without asking the origin (300–86400, default 3600). Older copies are still served and refreshed in the background with a conditional request.
Bot cache: seconds after which a copy is no longer served and is fetched again (300–86400, default 86400).
Crawlers the bot cache serves. Empty means all of them.
Wildcard path patterns (/api/*) never served from the bot cache.
Notify the owner when a subdomain suffers a sustained origin outage.
Per-minute origin-error percentage that counts as “down”.
Minutes the domain must stay down before an incident opens.
Minimum origin-eligible requests in the window — the traffic floor below which no incident opens.
Minimum populated one-minute buckets required in the window.
Consecutive clear minutes before an incident resolves.
Paused for billing. The edge refuses the domain’s TLS handshake, so visitors get a connection error. Clears automatically once the wallet is no longer negative.
The legacy TXT record that proves ownership of an external-DNS domain.
Still accepted, but new domains verify with the CNAME in
ssl_delegation, which also keeps their certificate renewing — prefer
that one.
object
Name to create the TXT record at.
Exact TXT value to publish.
An external-DNS domain’s verification record: one CNAME, created once
and never rotated. It proves ownership (a pending domain activates when
it is found) and stays in place afterwards as the domain’s connection
to NSIN, which is what lets NSIN issue and renew the certificate for the
apex and its wildcard. Once it has passed, removing or changing it
marks the domain moved — it keeps serving for a 3-day grace period,
then is disabled — exactly as a managed domain whose nameservers leave.
object
Name to create the CNAME at
The CNAME target
Whether the last live check found this domain’s delegation in place.
When the last check ran.
When the delegation last passed.
Why the last check failed — or, with ok true, a CAA policy on the
domain that prevents Let’s Encrypt from issuing.
How often NSIN re-checks the record on its own.
The canonical (first) accepted nameserver set.
Every accepted nameserver set. The delegation must match exactly one set in full — sets cannot be mixed.
The nameservers currently observed in the parent zone.
Your role on a domain. owner is implicit for the domain’s creator and
for global admins; the other three are grantable via sharing.
How often the background checker re-checks the delegation.
Whose wallet this domain’s charges come out of. Always present —
it falls back to the owner — so a client can name the payer
without a second request. Change it with
PUT /domains/{domain}/billing-member.
object
Who made the nomination. Absent when the owner pays.
True when no nomination is in force and the domain owner pays. The owner being named explicitly is stored as no nomination, so this never disagrees with ownership.
Example
{ "ssl_delegation": { "type": "CNAME" }, "domain": { "name": "example.com", "status": "pending", "dns_mode": "managed", "cache_cap_mb": 128, "hsts_max_age_sec": 0, "min_tls_version": "1.2", "origin_protocol": "http1", "bot_cache_kinds": [ "googlebot" ], "verification": { "type": "TXT" }, "ssl_delegation": { "type": "CNAME" }, "my_role": "owner", "my_permissions": [ "domain.view" ] }}The key exceeded its request budget (300 requests per minute by default).
The single error shape used by every endpoint.
object
Human-readable description of what went wrong.
Examples
{ "error": "rate limit exceeded"}