Custom Domains

Custom Domains

Bring your own domain so endpoints publish at app.yourcompany.com instead of a shared system domain. Manage domains in the dashboard under Domains (/account/domains). Custom domains are plan-gated — your plan must include the custom-domains entitlement, which also caps how many you can add (-1 means unlimited).

Two provisioning modes

When you add a domain you choose how its DNS and TLS are handled. The mode is fixed at creation time.

Manual mode carries no DNS credentials, so Ngris never edits records on your behalf and DNS-01 auto-issuance does not run — that's why a manual domain expects an uploaded certificate.

Adding a domain (auto mode)

In the dashboard, open Domains and click New Domain (/account/domains/new). Enter the domain name, choose Automatic, pick your DNS provider and supply its credentials, then click Connect & add domain. The page then follows the certificate issuance until it is done. Supported providers:

• Cloudflare — API Token + Zone ID
• AWS Route 53 — Access Key + Secret + Region
• DigitalOcean — API Token
• Namecheap — API User + Key + Client IP
• cPanel — URL + Username + API Token + Zone
• Webmin — URL + Username + Password + Domain

Your credentials are validated against the provider before anything is saved — bad or insufficient credentials are flagged on the DNS-credentials field. Stored credentials are encrypted at rest. Once saved, the domain enters pending_issuance and an ACME issue job is queued to mint the wildcard certificate.

Adding a domain (manual mode) & CNAME validation

In the dashboard, open Domains and click New Domain (/account/domains/new). Enter the domain name and choose Manual — no credentials needed. The page then walks you through three steps: Verify ownership, Point DNS and Certificate. You can leave the last two for later and finish them from the Domains page.

Prove you own the domain

Before a manual domain is added, you prove you control it with a TXT record. The dashboard shows the exact record for your account and domain:

Create it at your DNS provider, then click Verify ownership. Ngris reads the record directly from your domain's authoritative nameservers. Until it is found, nothing is created and the name is not reserved — if the record isn't visible yet (DNS changes can take a few minutes), just try again. The same record stays valid, so you can come back later. Over the API: GET /v1/domains/self/verification?name=yourdomain returns the record, and POST /v1/domains/self with "provisioning_mode": "manual" answers 400 with code domain_txt_not_verified until it is published. Once verified you may remove the TXT record.

Point your domain at ngris

Once added, the domain is in the pending_cname state and the dashboard shows you the exact record to add. The DNS-records view for a manual domain is read-only and returns the required records:

Validate the CNAME

After you add the *.yourdomain CNAME → cname.ngris.io record at your provider, click Check DNS in the add-domain page (or Validate CNAME on the Domains page later). Ngris probes a concrete subdomain that your wildcard must cover and confirms it is a CNAME chain ending at the target. A flattened / ALIAS record that only returns an IP is not accepted.

• Not yet resolving — you get a message telling you exactly which record to add; DNS changes can take a few minutes to propagate, so retry.
• Resolved — the domain advances from pending_cname to awaiting_cert. The next step is uploading your TLS certificate. If you already uploaded one for the domain, it becomes active right away.

Trying to edit DNS records on a manual domain through the dashboard is refused — those records live at your own provider.

Domain status

The dashboard surfaces the domain's lifecycle state as a status pill:

Certificates & DNS records

Auto mode — ACME wildcard

Auto domains get a wildcard certificate issued by ACME over DNS-01 and renewed automatically before expiry. You can trigger a manual Re-issue SSL from the domain's actions if needed, and watch live status via the ACME-status poll.

Manual mode — uploaded certificate

After CNAME validation, upload your own certificate (PEM, with private key) for the domain from its certificates view. The domain becomes active once a valid *.yourdomain certificate is in place. Manual certs don't auto-renew via DNS-01 — Ngris emails the account owner before a manual certificate expires so you can upload a fresh one.

Per-endpoint certificate

By default an endpoint is served with its domain's default certificate. To serve one endpoint with a different certificate, open Endpoints → Settings → Overview: the HTTPS certificate card shows the certificate served now (name, hostnames, expiry) and lets you pick another. The list holds only certificates of the endpoint's domain that cover its hostname, exactly or through a wildcard such as *.yourdomain. That includes certificates ngris has provided for your account, labelled Provided by ngris. Choose Domain default (recommended) to go back to the domain's certificate. Picking a certificate needs a plan with custom SSL certificates. Endpoints on ngris domains (such as *.ngris.dev) always use the ngris certificate.

DNS records (auto mode)

For auto domains, the dashboard offers full DNS record management against your provider — A, AAAA, CNAME, TXT, MX, NS, SRV, CAA — each with name, content, TTL and optional priority. Manual domains show read-only instructions instead.

Domain registration expiry

Separately from its TLS certificate, a domain has a registration at your registrar that has to be renewed. Ngris tracks the registration expiry of every custom domain, whatever its DNS provider — Cloudflare, Route 53, cPanel, any other provider above, or none at all (manual mode). It warns you before the registration expires and suspends the domain only once the registration has actually lapsed.

Where the expiry date comes from

Ngris reads each live custom domain's registration from the first of these that has it:

1. Cloudflare Registrar — when the domain's DNS provider is Cloudflare and Cloudflare has a registrar record for it;
2. otherwise RDAP — the TLD registry's RDAP server, found via the IANA RDAP bootstrap;
3. otherwise WHOIS — for TLDs without RDAP.

Each domain is looked up about once a day; a newly added domain within about 15 minutes. There is nothing to set up.

In the dashboard under Domains (/account/domains), the Domain Expires column shows the date plus where it came from and when it was checked — for example RDAP · checked 2 h ago. If the last lookup failed, it says Couldn't check the registration (hover it for the reason). A failed or empty lookup never suspends a domain; the next lookup simply tries again.

Over the API the same information is the registration object, returned by GET /v1/domains/self/{uuid}/acme/status and on your own domains in the domain lists.

Warnings before expiry

For every domain with a known expiry date, you get a warning email 30, 14 and 7 days before the registration expires. Renew the domain at your registrar before the expiry date and it keeps running — there is nothing to change on Ngris.

When a lookup finds that a domain you were warned about has been renewed, you get one email — Domain <name> was renewed — and the reminders for it stop.

Auto-renew grace: a later date isn't always a renewal

Many registries automatically move a domain's expiration date a year forward on the expiry day, even if nobody has paid. That is the auto-renew grace period (up to 45 days); if the renewal isn't paid, the domain then goes into the redemption period (30 days), then pending delete. So a new date on its own doesn't prove the domain was renewed.

Ngris reads the registry's EPP status codes. A date shown together with any of these statuses is not treated as a renewal:

• auto renew period
• redemption period
• pending delete
• pending restore
• client hold
• server hold

The stored expiry date then stays the old one — so the reminders don't stop — and the Domains page shows Registry: <status> — not renewed yet. A renewal counts only when the new date is more than 7 days in the future and none of those statuses is present.

Suspension when the registration lapses

Once the expiry date has passed, Ngris looks the registration up again, fresh, and suspends the domain only when that lookup shows the registration has actually lapsed:

• Registry data (RDAP / WHOIS): the registry reports redemption period, pending delete, client hold or server hold, or the expiry date is still in the past more than 45 days after it;
• Cloudflare Registrar data: its expiry date has passed.

A domain in the auto-renew grace keeps working, a domain you already renewed is not suspended, and a failed or empty lookup never suspends anything. When the domain is suspended (status expired):

• the domain stops being served and all its endpoints go offline;
• you get a Domain suspended (expired) email: renew the domain at your registrar within 30 days — Ngris re-checks every 4 hours and reactivates it automatically, or you can click Check again.

Automatic reactivation after you renew

While the domain is suspended, Ngris re-checks its registration (from the same sources) every 4 hours. As soon as a lookup shows the domain renewed — an expiry date more than 7 days in the future and none of the grace or hold statuses above — the domain is reactivated automatically; there is nothing to switch back on:

• the domain and each of its endpoints come back exactly as they were before the suspension;
• certificate renewal resumes — if a certificate renewal is due, it is queued right away;
• you get one email: Domain <name> was renewed and is no longer suspended.

Only a fresh, successful lookup counts. An error, an empty answer, an expiry date that is still in the past, or a new date the registry still shows with a grace or hold status leaves the domain suspended.

Check again

You don't have to wait for the next automatic check. In the dashboard under Domains (/account/domains), a suspended domain shows its suspension — when it expired and when it will be deleted — and a Check again button. It asks for an immediate re-check, which is answered within seconds. Check again can be used once per 10 minutes per domain, whoever clicks it (admins included). The same action is available over the API: POST /v1/domains/self/{uuid}/expiry-check.

If the domain is still suspended after a check, the check tells you why:

Deletion after 30 days

If the domain is still not renewed 30 days after it was suspended, Ngris runs one last check and then permanently deletes the domain, its endpoints and its certificates. A domain renewed at the last minute is reactivated instead of deleted.

What you can't do while it's suspended

Only the renewal lifts the suspension. Until then these actions are refused with 409 and the error code domain_expiry_suspended:

• switching the domain back on by hand (is_active on PUT /v1/domains/self/{uuid});
• switching it to a different DNS provider;
• re-issuing its SSL certificate (Re-issue SSL).

Special cases

• Your account is suspended. A renewed domain stays suspended until the account is active again. It then comes back on the next check (within 4 hours), or right away with Check again.
• Your plan no longer includes custom domains. The renewed domain comes back, but disabled because of your plan — it stays disabled until you upgrade to a plan that includes custom domains.
• The registration can't be looked up. A failed lookup never suspends a domain and never counts as a renewal; the Domains page shows Couldn't check the registration with the reason, and the next lookup tries again. If Check again answers unsupported (rare, see above), contact support.