Custom Domain

How it works

api.yourdomain.com  →  CNAME  →  cname.frostauth.cc

Setup

Step 1 — Navigate to Settings

Step 2 — Enter your subdomain

• Use a bare hostname — no https://, no port, no path.
• The input is lowercased and trimmed automatically.
• The domain must be unique across all Frost Auth products. If another operator already claimed it, the save will fail.

Changing an existing domain resets its verification status. You must re-verify after every change.

Step 3 — Create the CNAME record

Step 4 — Verify

• Verified — the CNAME matches. The domain is added to the CORS allow-list within 60 seconds (the cache refresh interval).
• Not verified yet — the CNAME either doesn’t exist yet or points somewhere else. DNS propagation can take up to an hour. Do not keep clicking verify in a loop; wait and try again.

Step 5 — Update your SDK base URL

https://api.yourdomain.com/api/v1

Responses

Save domain (PATCH /api/v1/settings/:productId)

{
  "success": true,
  "response": {
    "data": {
      "domain": "api.yourdomain.com",
      "domainVerified": false,
      "domainCheckedAt": null
    }
  }
}

{
  "error": true,
  "response": {
    "code": 400,
    "message": "Enter a hostname such as api.yourdomain.com — no scheme, port or path"
  }
}

{
  "error": true,
  "response": {
    "code": 403,
    "message": "Custom domains need the Pro plan"
  }
}

{
  "error": true,
  "response": {
    "code": 409,
    "message": "That domain is already in use"
  }
}

{
  "error": true,
  "response": {
    "code": 404,
    "message": "Product not found"
  }
}

{
  "error": true,
  "response": {
    "code": 500,
    "message": "Something went wrong"
  }
}

Verify domain (POST /api/v1/settings/:productId/domain/verify)

{
  "success": true,
  "response": {
    "data": {
      "domain": "api.yourdomain.com",
      "domainVerified": true,
      "records": ["cname.frostauth.cc"]
    }
  }
}

{
  "error": true,
  "response": {
    "code": 400,
    "message": "Add a domain first"
  }
}

{
  "error": true,
  "response": {
    "code": 403,
    "message": "Custom domains need the Pro plan"
  }
}

{
  "error": true,
  "response": {
    "code": 409,
    "message": "No CNAME found on api.yourdomain.com yet — DNS can take up to an hour"
  }
}

{
  "error": true,
  "response": {
    "code": 409,
    "message": "api.yourdomain.com points to something-else.com — it must point to cname.frostauth.cc"
  }
}

{
  "error": true,
  "response": {
    "code": 404,
    "message": "Product not found"
  }
}

{
  "error": true,
  "response": {
    "code": 429,
    "message": "Too many requests"
  }
}

{
  "error": true,
  "response": {
    "code": 500,
    "message": "Failed to verify the domain"
  }
}

Errors

Behavior

• DNS verification is a live lookup, not a poll. Each click of Verify triggers one resolveCname call. There is no background polling loop.
• Changing the domain resets verification. Any PATCH that includes domain sets domainVerified: false and domainCheckedAt: null. The old domain stops being trusted on the next cache refresh (within 60 seconds).
• CORS trust is cached. Verified domains are held in an in-memory Set per instance, backed by a Redis cache with a 60-second TTL. After verification succeeds, the cache is explicitly invalidated so other instances pick it up on their next tick rather than waiting out the window.
• Only HTTPS origins are accepted. The CORS check parses the origin URL and refuses any protocol other than https:. A custom domain without TLS would send session cookies in clear text.
• TLS certificates are separate from verification. Verification proves the CNAME points at FrostAuth. Serving traffic also requires the edge to hold a certificate for the hostname. The edge’s on-demand TLS hook calls GET /settings/domain/issuable?domain=... before issuing one — if your domain is verified, it answers 200 and the certificate is minted. Until that happens, HTTPS connections to your domain will fail even though the dashboard says verified.
• Domain uniqueness is platform-wide. Two products across different accounts cannot share the same custom domain. The database enforces this with a unique constraint.
• Revoking a domain (clearing the field) removes it from the verified set on the next cache refresh. Requests to the old domain will start receiving CORS refusals once the cache expires.