# Custom Domain API

> Let the customers of a SaaS use their own domain (such as forms.acme.com) for their workspace: one API call returns the two DNS records the customer adds; the edge verifies them, issues the HTTPS certificate on demand, and forwards every request to the SaaS backend with a signed assertion naming the workspace. Open source (Apache 2.0), hosted (Free and paid plans) or self-hosted.

Key facts for integrating:
- API base URL on the Free plan: https://edge.customdomainapi.com/v1 (Authorization: Bearer <API key>). OpenAPI: https://edge.customdomainapi.com/v1/openapi.json
- Customers CNAME their hostname to edge.customdomainapi.com (Free) and add a TXT record; both come back from POST /v1/domains.
- The backend must select the tenant from the verified X-Custom-Domain-Assertion header, never from the Host header.
- Python SDK: pip install custom-domain-sdk.
- Sign up for Free: https://app.customdomainapi.com

## Docs

- [Overview](https://customdomainapi.com/docs/index.md): Everything you need to let your SaaS customers use their own domain with Custom Domain API, from the first API call to verifying requests at your origin.
- [Quickstart](https://customdomainapi.com/docs/quickstart.md): Let a customer of your SaaS use their own hostname in about fifteen minutes on the Free plan, from sign-up to HTTPS, with the API and the Python SDK.
- [How it works](https://customdomainapi.com/docs/how-it-works.md): How Custom Domain API verifies a customer's hostname, issues its certificate and routes each request to the right workspace, and what each domain status and check means.
- [API reference](https://customdomainapi.com/docs/api.md): The Custom Domain API v1 reference. Register customer hostnames, read their DNS records and checks, re-check and delete them, with idempotency, pagination, errors and limits.
- [Verifying requests](https://customdomainapi.com/docs/verify-requests.md): How your origin verifies the edge's signed X-Custom-Domain-Assertion header and selects the workspace from it, with the Python SDK, a Node.js example and the exact algorithm for any language.
- [Webhooks](https://customdomainapi.com/docs/webhooks.md): Get notified when a customer's domain is ready, needs attention, recovers or is deleted. Events, payloads, HMAC signatures, retries and replay.
- [Your customers' DNS](https://customdomainapi.com/docs/customer-dns.md): The two DNS records your customers add to connect their own domain to your SaaS, how to word the instructions, and the usual DNS console mistakes.
- [For AI coding agents](https://customdomainapi.com/docs/ai-agents.md): A compact, complete brief for AI coding agents integrating Custom Domain API into a SaaS codebase. Contracts, invariants, and a step-by-step checklist.
- [Self-hosting](https://customdomainapi.com/docs/self-hosting.md): Run the open-source Custom Domain service on your own server or cloud, with one-click templates for Azure, AWS, Google Cloud, Hetzner and DigitalOcean.

## Optional

- [All docs in one file](https://customdomainapi.com/llms-full.txt)
- [Source code and operator docs](https://github.com/sireto/custom-domain)
- [Python SDK](https://github.com/sireto/custom-domain/blob/main/sdk/README.md)
- [Terms](https://customdomainapi.com/terms/), [Acceptable use](https://customdomainapi.com/acceptable-use/)