Custom Domains

Custom Domains

What This Is

By default, canisters are accessible at <canister-id>.icp.net. The custom domains service lets you serve any canister under your own domain (e.g., yourdomain.com). You configure DNS, deploy a domain ownership file to your canister, and register via a REST API. The HTTP gateways then handle TLS certificate provisioning, renewal, and routing automatically.

Custom domains work at the boundary node level — they map a domain to any canister ID via DNS. This works with any canister that can serve /.well-known/ic-domains over HTTP, not just asset canisters. That includes asset canisters, Juno satellites, and custom canisters implementing http_request.

Prerequisites

• A registered domain from any registrar (e.g., Namecheap, GoDaddy, Cloudflare)
• Access to edit DNS records for that domain
• A deployed canister that serves /.well-known/ic-domains over HTTP (asset canisters, Juno satellites, or any canister implementing http_request)
• curl for the registration API calls
• jq (optional, for formatting JSON responses)

Mistakes That Break Your Setup

1. Not disabling your DNS provider's SSL/TLS. Providers like Cloudflare enable Universal SSL by default. This interferes with the ACME challenge the IC uses to provision certificates and can prevent certificate renewal. Disable any certificate/SSL/TLS offering from your DNS provider before registering.

2. Setting a CNAME on the apex domain. Many DNS providers don't allow CNAME records on the apex (e.g., example.com with no subdomain). Use ANAME or ALIAS record types (CNAME flattening) if your provider supports them. Otherwise, use a subdomain like www.example.com.

3. Missing the _acme-challenge CNAME. Without _acme-challenge.CUSTOM_DOMAIN pointing to _acme-challenge.CUSTOM_DOMAIN.icp2.io, the HTTP gateways cannot obtain a TLS certificate. Registration will fail.

4. Multiple TXT records on _canister-id. If more than one TXT record exists for _canister-id.CUSTOM_DOMAIN, registration fails. Keep exactly one containing your canister ID.

5. Forgetting the .well-known/ic-domains file. The canister must serve /.well-known/ic-domains listing your custom domain. Without it, domain ownership verification fails during registration.

6. Stale _acme-challenge TXT records from your DNS provider. Previous ACME challenges by your provider may leave TXT records on _acme-challenge.CUSTOM_DOMAIN that don't appear in your dashboard. These conflict with the IC's ACME flow. Disable all TLS offerings from your provider to clear them. Verify with dig TXT _acme-challenge.CUSTOM_DOMAIN.

7. Not explicitly registering the domain. DNS configuration alone is not enough. You must call POST /custom-domains/v1/CUSTOM_DOMAIN to start registration. It is not automatic.

8. Setting HttpAgent's host to your custom domain. host is the API endpoint canister calls go to, not the domain your frontend is served from. Your custom domain is the HTTP gateway — it does not serve /api/v2, so pointing host at it (or at window.location.origin) makes calls fail. You do not need to set host: a recent @icp-sdk/core HttpAgent resolves an omitted host to https://icp-api.io (the mainnet API boundary nodes) on a custom domain. Leave it unset, or set it explicitly to https://icp-api.io — never the gateway domain.

9. Adding a custom domain to an app that already has users. II principals are per-origin, so the new domain hands every returning user a brand-new account. Pin a derivation origin — the canister address, which a custom domain can never displace — and list the domain in .well-known/ii-alternative-origins before the domain goes live. A domain that has already collected sign-ins cannot be repointed without orphaning those accounts. See the internet-identity skill.

Implementation

Step 1: Configure DNS Records

Add three DNS records (replace CUSTOM_DOMAIN with your domain, e.g., app.example.com):

Some DNS providers omit the main domain suffix. For app.example.com on such providers:

• app instead of app.example.com
• _canister-id.app instead of _canister-id.app.example.com
• _acme-challenge.app instead of _acme-challenge.app.example.com

For apex domains without CNAME support, use your provider's ANAME or ALIAS record type pointing to CUSTOM_DOMAIN.icp1.io.

Step 2: Create the ic-domains File

Your canister must serve /.well-known/ic-domains over HTTP. Create this file listing each custom domain on its own line:

app.example.com
www.example.com

Frontend canister users: place .well-known/ inside your public/ directory (Vite projects) or alongside your source files so it ends up in your dir. With the recommended @dfinity/static-site recipe, .well-known/ is uploaded automatically (no config needed). With the legacy @dfinity/asset-canister recipe, ensure .ic-assets.json5 includes { "match": ".well-known", "ignore": false } so the hidden directory gets deployed. See the static-site skill for details on file placement.

Custom http_request canisters: serve the file contents at /.well-known/ic-domains directly from your HTTP request handler.

Step 3: Deploy

Deploy your canister so that /.well-known/ic-domains is accessible at https://<canister-id>.icp.net/.well-known/ic-domains.

Step 4: Validate

Check DNS records and canister configuration before registering:

curl -sL -X GET "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN/validate" | jq

Success response:

{
  "status": "success",
  "message": "Domain is eligible for registration: DNS records are valid and canister ownership is verified",
  "data": {
    "domain": "CUSTOM_DOMAIN",
    "canister_id": "CANISTER_ID",
    "validation_status": "valid"
  }
}

If validation fails, common errors and fixes:

Step 5: Register

curl -sL -X POST "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

Success response:

{
  "status": "success",
  "message": "Domain registration request accepted and may take a few minutes to process",
  "data": {
    "domain": "CUSTOM_DOMAIN",
    "canister_id": "CANISTER_ID"
  }
}

Step 6: Wait for Certificate Provisioning

Poll until registration_status is registered:

curl -sL -X GET "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

Status values: registering → registered (success), or failed (check error message).

After registered, wait a few more minutes for propagation to all HTTP gateways before testing.

Updating a Custom Domain

To point an existing custom domain at a different canister:

1. Update the _canister-id TXT record to the new canister ID.
2. Notify the service:

curl -sL -X PATCH "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

3. Check status:

curl -sL -X GET "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

Removing a Custom Domain

1. Remove the _canister-id TXT record and _acme-challenge CNAME from DNS.
2. Notify the service:

curl -sL -X DELETE "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

3. Confirm deletion (should return 404):

curl -sL -X GET "https://icp.net/custom-domains/v1/CUSTOM_DOMAIN" | jq

HttpAgent Configuration

A frontend served from your custom domain still makes its canister calls through the mainnet API boundary nodes (https://icp-api.io), not through the domain it is served from. HttpAgent's host is that API endpoint — not your frontend's origin. The custom domain is the HTTP gateway and does not serve /api/v2.

You do not need to set host. When it is omitted, a recent @icp-sdk/core HttpAgent resolves to https://icp-api.io on a custom domain (and on icp.net). Do not point host at your custom domain or window.location.origin — that is the gateway, so calls would fail.

import { HttpAgent } from "@icp-sdk/core/agent";

// host omitted on a custom domain → resolves to https://icp-api.io
const agent = await HttpAgent.create();

// equivalent, explicit:
const agentExplicit = await HttpAgent.create({ host: "https://icp-api.io" });

Deploy & Test

# 1. Deploy your canister with the ic-domains file served at /.well-known/ic-domains

# 2. Validate DNS + canister config
curl -sL -X GET "https://icp.net/custom-domains/v1/yourdomain.com/validate" | jq

# 3. Register
curl -sL -X POST "https://icp.net/custom-domains/v1/yourdomain.com" | jq

# 4. Poll until registered
curl -sL -X GET "https://icp.net/custom-domains/v1/yourdomain.com" | jq

Verify It Works

# 1. Verify DNS records
dig CNAME yourdomain.com
# Expected: yourdomain.com. CNAME yourdomain.com.icp1.io.

dig TXT _canister-id.yourdomain.com
# Expected: "<your-canister-id>"

dig CNAME _acme-challenge.yourdomain.com
# Expected: _acme-challenge.yourdomain.com. CNAME _acme-challenge.yourdomain.com.icp2.io.

# 2. Verify ic-domains file is served by the canister
curl -sL "https://<canister-id>.icp.net/.well-known/ic-domains"
# Expected: your domain listed

# 3. Verify registration status is "registered"
curl -sL -X GET "https://icp.net/custom-domains/v1/yourdomain.com" | jq '.data.registration_status'
# Expected: "registered"

# 4. Verify the custom domain serves your canister
curl -sI "https://yourdomain.com"
# Expected: HTTP/2 200

# 5. Verify no stale ACME TXT records
dig TXT _acme-challenge.yourdomain.com
# Expected: no TXT records (only the CNAME)