Custom domains

Serve the sign-in experience on your own domain, with DNS TXT ownership proof, host-based tenant resolution and automatic TLS.

A custom domain lets your users sign in on id.yourbrand.com instead of accounts.obexal.com. Once the domain is verified, the sign-in page is served there with your branding, and the tenant is resolved automatically from the Host of the request: pre-auth flows on your domain need no tenant header. Managing domains requires the tenant:manage permission.

How it works

Three mechanisms cooperate, and each one is gated on verification:

• Ownership proof: you prove control of the domain by publishing a DNS TXT record containing a challenge token.
• Tenant resolution: only a verified domain resolves to your tenant. An unverified entry resolves nothing: no theming, no sign-in, no certificate.
• Automatic TLS: the certificate is issued on demand at the first HTTPS visit, and issuance is only authorized for verified tenant domains.

A domain is globally unique across the platform: one domain belongs to at most one tenant. Registering a domain already taken returns 409.

Connect your domain in four steps

1. Declare the domain

curl -X POST https://accounts.obexal.com/v1/admin/domains \
  -H "Authorization: Bearer $OBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"id.yourbrand.com"}'

{
  "domain": "id.yourbrand.com",
  "verified": false,
  "createdAt": "2026-07-02T09:15:00Z",
  "dnsRecord": {
    "type": "TXT",
    "name": "_obexal-challenge.id.yourbrand.com",
    "value": "k3J9x...challenge token..."
  }
}

2. Publish the TXT proof

At your DNS provider, create the TXT record exactly as returned: name _obexal-challenge.id.yourbrand.com, value = the challenge token. DNS propagation can take from minutes to hours depending on your provider.

3. Verify ownership

curl -X POST https://accounts.obexal.com/v1/admin/domains/id.yourbrand.com/verify \
  -H "Authorization: Bearer $OBX_TOKEN"
# {"verified":true}

A {"verified":false} response means the record was not found yet (propagation, typo): fix and retry, the call is safe to repeat. Verification is a one-time check; once verified, the domain stays verified.

4. Point the domain at Obexal

Create the A/AAAA or CNAME record so that id.yourbrand.com resolves to the Obexal platform. The first HTTPS visit then triggers certificate issuance, and the sign-in page is served on your domain.

Automatic TLS, protected against abuse

Certificates for custom domains are issued on demand, at the first TLS handshake for the hostname. Before issuing, the platform's reverse proxy asks the API for authorization:

curl -i https://accounts.obexal.com/v1/tls/authorize?domain=id.yourbrand.com
# 200 if id.yourbrand.com is a VERIFIED tenant domain, 404 otherwise

Only verified tenant domains get a 200. Without this guard, anyone pointing arbitrary hostnames at the platform could exhaust ACME certificate quotas (a denial of service). The endpoint is unauthenticated (it is called server-to-server by the proxy) but only reveals the existence of domains that are already publicly in use.

Only verified domains resolve

Host-based tenant resolution considers verified domains only. This is what makes the mechanism safe: an attacker who declares your domain in their own tenant but cannot publish your DNS record gets nothing. Verification, not declaration, is what activates sign-in, theming and TLS.

Manage your domains

# List (pending domains include their dnsRecord so you can re-read the challenge)
curl https://accounts.obexal.com/v1/admin/domains \
  -H "Authorization: Bearer $OBX_TOKEN"

# Remove a domain (idempotent)
curl -X DELETE https://accounts.obexal.com/v1/admin/domains/id.yourbrand.com \
  -H "Authorization: Bearer $OBX_TOKEN"

Domain additions, verifications and deletions are recorded in the audit log.