Skip to content
Dashboard
Theme
Theme

Add a custom domain

POST /v1/custom_domains: Add a custom domain.

View Markdown

DNS records returned.

POST /v1/custom_domains

Email sender domains are bounded to 100 per environment. Portal hostnames (Pro plans and above), broker, SCIM and combined broker_scim hostnames (Business plans and above; at most 100 hostnames per environment, a plan that does not allow the type answers plan_limit_reached) are registered with Cloudflare for SaaS with our origin-pull certificate attached; the response lists the CNAME to publish and the ownership and certificate TXT records Cloudflare returned. The hostname stays pending until both the hostname and its certificate are active, and serves traffic only for connections of its own environment. A hostname the provider refuses answers parameter_invalid; a hostname already registered answers resource_already_exists. There is no platform-wide limit on signin hostnames. Once one is verified and made the environment’s active sign-in host (PUT /v1/environment/signin_host), new end-user passkeys bind to it as their own WebAuthn relying party (signin_hostname_limit_reached is no longer returned).

Scope
custom_domains:write
Auth
Secret key (sk_…)
Since
1.0
  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

  • Idempotency-Key string

    Honoured for 24 h; a replay returns the original response.

    min length 1 · max length 255

  • type string Required

    signin (Pro and above) serves the environment’s hosted sign-in app on the hostname; once verified it is accepted as a sign-in API (CORS) and passkey origin for that environment only. broker_scim (Business and above) serves sign-in and SCIM on one hostname, as a vendor that did both on one host (a self-hosted Polis) did: paths under /scim/ and the legacy SCIM base paths of imported directories reach SCIM only, every other path reaches sign-in only.

    one of portal, broker, scim, email, signin, broker_scim

  • hostname string Required

    min length 1 · max length 253

  • spf_record string

    Email only. Exact SPF TXT configuration to verify at the sender domain.

    min length 1 · max length 1024

  • dkim_records array of DnsRecord

    Email only. Exact DKIM TXT or CNAME configuration records.

    min items 1 · max items 3

Errors share one shape; see the error code catalogue.

curl -X POST \
"https://api.ohauthcat.com/v1/custom_domains" \
-H "Authorization: Bearer $OHAUTHCAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "portal",
"hostname": "acme.com"
}'
Response 201
{
"id": "cdom_01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"object": "custom_domain",
"type": "portal",
"hostname": "acme.com",
"state": "pending",
"dns_records": [
{
"type": "CNAME",
"name": "Acme Corp",
"value": "enterprise"
}
],
"created_at": "2026-01-15T09:30:00Z"
}