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 /), 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
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Honoured for 24 h; a replay returns the original response.Idempotency-Keystringmin length 1 · max length 255
Request body
Section titled “Request body”typestring Requiredsignin(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_scimhostnamestring Requiredmin length 1 · max length 253
Email only. Exact SPF TXT configuration to verify at the sender domain.spf_recordstringmin length 1 · max length 1024
Email only. Exact DKIM TXT or CNAME configuration records.dkim_recordsarray of DnsRecordmin items 1 · max items 3
Responses
Section titled “Responses”- 201 OK CustomDomain
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 409 Codes: idempotency_key_reused and resource-specific conflicts. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
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"}'const response = await fetch("https://api.ohauthcat.com/v1/custom_domains", { method: "POST", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "type": "portal", "hostname": "acme.com" }),});const data = await response.json();import osimport requests
response = requests.post( "https://api.ohauthcat.com/v1/custom_domains", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"}, json={ "type": "portal", "hostname": "acme.com", },)data = response.json(){ "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"}