Custom Domains API

Custom Domains allow you to serve Auris hosted login pages and OAuth flows under your own branded domain (e.g., auth.yourdomain.com) instead of the default Auris domain. This provides a seamless, white-label experience where your users never see the Auris brand.

The custom domain lifecycle follows these steps:

1. Add the domain via the API
2. Configure DNS — add the CNAME or TXT record Auris provides
3. Verify — Auris checks the DNS record and provisions an SSL certificate
4. Activate — set the domain as the primary domain for your tenant

Once active, all OAuth redirects, hosted login pages, email links, and SDK configurations use your custom domain.

All endpoints require the x-tenant header and a valid Bearer token. Custom domain management requires admin-level access.

List Custom Domains

Success response

{
  "ok": true,
  "data": [
    {
      "id": "cd_abc123",
      "domain": "auth.acme-corp.com",
      "status": "ACTIVE",
      "sslStatus": "ACTIVE",
      "verificationMethod": "CNAME",
      "verificationToken": "auris-verify-abc123def456",
      "primaryDomain": true,
      "createdAt": "2025-01-15T10:00:00Z",
      "verifiedAt": "2025-01-15T10:45:00Z"
    },
    {
      "id": "cd_def456",
      "domain": "login.acme.io",
      "status": "PENDING",
      "sslStatus": "PENDING",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-ghi789jkl012",
      "primaryDomain": false,
      "createdAt": "2025-02-10T08:00:00Z",
      "verifiedAt": null
    }
  ]
}

Domain Status Lifecycle

SSL Status

Add a Custom Domain

Request body

{
  "domain": "auth.acme-corp.com"
}

Success response

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "PENDING",
    "sslStatus": "PENDING",
    "verificationMethod": "CNAME",
    "verificationToken": "auris-verify-mno345pqr678",
    "primaryDomain": false,
    "dnsRecord": {
      "type": "CNAME",
      "host": "auth.acme-corp.com",
      "value": "your-auris-domain.com"
    },
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

After creating the domain, add the DNS record shown in dnsRecord at your domain registrar. The record type depends on the domain configuration:

CNAME verification (for subdomains like auth.acme-corp.com):

CNAME auth.acme-corp.com → your-auris-domain.com

TXT verification (alternative method):

TXT _auris-verify.auth.acme-corp.com → auris-verify-mno345pqr678

Once the DNS record is propagated, call the verify endpoint.

Error codes

Verify a Domain

Request: No body required.

Success response — verified

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "ACTIVE",
    "sslStatus": "PENDING",
    "verifiedAt": "2025-02-18T10:45:00Z"
  }
}

After verification succeeds, the SSL status transitions from PENDING to ACTIVE within a few minutes as the certificate is provisioned.

Success response — not yet propagated

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "PENDING",
    "message": "DNS record not found yet. DNS propagation can take up to 48 hours."
  }
}

Success response — verification failed

{
  "ok": true,
  "data": {
    "id": "cd_ghi789",
    "domain": "auth.acme-corp.com",
    "status": "FAILED",
    "message": "CNAME record found but points to an incorrect target. Expected: your-auris-domain.com, Found: other-service.com"
  }
}

Error codes

Delete a Custom Domain

Success response

{
  "ok": true,
  "data": { "deleted": true }
}

Error codes

Set Primary Domain

Setting a domain as primary causes all Auris-generated URLs (OAuth redirect base, email links, OIDC discovery issuer) to use this domain instead of the default Auris domain.

Request body

{
  "primaryDomain": true
}

Success response

{
  "ok": true,
  "data": {
    "id": "cd_abc123",
    "domain": "auth.acme-corp.com",
    "primaryDomain": true,
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Error codes

How Custom Domains Work

When a custom domain is set as primary, the following Auris behaviors change:

DNS Verification Methods

Auris supports two DNS verification methods:

CNAME Verification (Recommended)

Used for subdomains. The CNAME record serves dual purpose — it verifies ownership and routes traffic to Auris.

Type:  CNAME
Host:  auth.acme-corp.com
Value: your-auris-domain.com
TTL:   3600 (or Auto)

TXT Verification

Alternative method when CNAME is not suitable. A separate TXT record is added under the _auris-verify subdomain.

Type:  TXT
Host:  _auris-verify.auth.acme-corp.com
Value: auris-verify-mno345pqr678
TTL:   3600 (or Auto)

With TXT verification, you must also configure a CNAME or A record separately to route traffic to Auris.

Permissions Reference

Custom domain management is typically restricted to tenant administrators. The permission is included in the default admin role.

Related

• Custom Domains Guide — Step-by-step domain setup and verification
• Custom Domains — Add and verify domains from the Console