Custom Domains

By default, Auris serves hosted login pages on a subdomain like your-tenant.accounts.altovar.net. Custom domains let you replace this with your own domain (e.g., auth.yourcompany.com), providing a fully branded authentication experience where users never see the Auris domain.

This guide covers adding a custom domain, completing DNS verification, and configuring your SDKs to use it.

What Custom Domains Do

When you configure a custom domain:

• The hosted login page is served at https://auth.yourcompany.com instead of https://your-tenant.accounts.altovar.net
• OAuth2 authorization and token endpoints use your domain
• OIDC Discovery (.well-known/openid-configuration) resolves under your domain
• JWKS endpoint for token verification uses your domain
• Emails sent to users (magic links, verification, password reset) contain links to your domain
• SSL certificates are automatically provisioned and renewed via Let’s Encrypt

Your users interact entirely with your brand, with no indication that Auris powers the authentication.

Prerequisites

Before setting up a custom domain, ensure you have:

• Administrative access to your DNS provider (e.g., Cloudflare, Route 53, GoDaddy)
• A subdomain reserved for authentication (e.g., auth.yourcompany.com, login.yourcompany.com, or id.yourcompany.com)
• An active Auris tenant on the Pro or Enterprise plan

Step 1: Add the Domain in Console

1. Open the Auris Console and navigate to Settings then Custom Domains
2. Click Add Domain
3. Enter your domain (e.g., auth.yourcompany.com)
4. Click Add

Auris generates a verification token and displays the DNS records you need to create. The domain status will show as Pending until verification is complete.

You can also add a domain via the API:

curl -X POST https://auth.yourdomain.com/api/custom-domains \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "auth.yourcompany.com"
  }'

Response:

{
  "ok": true,
  "data": {
    "id": "cd_abc123",
    "domain": "auth.yourcompany.com",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-a1b2c3d4e5f6",
    "sslStatus": "PENDING",
    "primaryDomain": false,
    "createdAt": "2026-01-15T10:00:00Z"
  }
}

Step 2: Configure DNS

Create two DNS records at your DNS provider:

Verification record:

Traffic record (create after verification):

DNS Provider Examples

Cloudflare:

1. Go to the DNS settings for your domain
2. Click Add Record
3. Set Type to TXT, Name to _auris-verification.auth, and Content to your verification token
4. Add the traffic CNAME: Name auth, Target your-tenant.accounts.altovar.net

AWS Route 53:

1. Open the hosted zone for your domain
2. Click Create Record
3. Record name: _auris-verification.auth
4. Record type: TXT
5. Value: your verification token (e.g. "auris-verify-a1b2c3d4e5f6")
6. TTL: 300

GoDaddy:

1. Go to DNS Management for your domain
2. Click Add under the records table
3. Type: TXT, Name: _auris-verification.auth, Value: your verification token, TTL: 600

Step 3: Wait for Verification and SSL

After creating the DNS records, Auris periodically checks for the verification record (every few minutes). You can also trigger a manual check:

1. In the Console, go to Settings then Custom Domains
2. Click the Check button next to your pending domain

Or via the API:

curl -X POST https://auth.yourdomain.com/api/custom-domains/cd_abc123/verify \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

Once DNS verification passes, the domain status changes to Verifying and Auris begins SSL provisioning. An SSL certificate is automatically issued via Let’s Encrypt. This typically completes within a few minutes.

When SSL is ready, the domain status changes to Active and the SSL status changes to Active. Your custom domain is now fully operational.

Verification Timeline

Step 4: Set as Primary Domain

If you have multiple custom domains (e.g., for different brands or regions), you can designate one as the primary domain. The primary domain is used in:

• Email links (magic links, verification, password reset)
• Default iss claim in JWTs
• OIDC Discovery document

In the Console, click the Set as Primary button on the domain you want to use as default. Or via the API:

curl -X PATCH https://auth.yourdomain.com/api/custom-domains/cd_abc123 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "primaryDomain": true }'

Using Custom Domains with the SDK

Once your custom domain is active, update the domain parameter in your SDK configuration to use it:

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'auth.yourcompany.com', // Your custom domain
  clientId: 'your-client-id',
  redirectUri: 'https://app.yourcompany.com/callback',
})

For React applications:

import { AurisProvider } from '@auris/react'
 
function App() {
  return (
    <AurisProvider
      domain="auth.yourcompany.com"
      clientId="your-client-id"
      redirectUri="https://app.yourcompany.com/callback"
    >
      <MyApp />
    </AurisProvider>
  )
}

For Next.js, update your environment variables:

NEXT_PUBLIC_AURIS_DOMAIN=auth.yourcompany.com
NEXT_PUBLIC_AURIS_CLIENT_ID=your-client-id
AURIS_JWKS_URL=https://auth.yourcompany.com/.well-known/jwks.json

The OIDC Discovery endpoint is available at:

https://auth.yourcompany.com/.well-known/openid-configuration

And the JWKS endpoint at:

https://auth.yourcompany.com/.well-known/jwks.json

Branding Configuration

Custom domains work together with the branding settings in the Console. To complete the white-label experience:

1. Go to Console then Branding
2. Upload your logo (displayed on the hosted login page)
3. Set the company name (shown in page titles and email headers)
4. Choose a background color or use a preset
5. Optionally upload a favicon for the hosted login page tabs

These branding settings apply to all hosted pages served on your custom domain.

Troubleshooting

DNS Records Not Found

Symptom: Domain stays in PENDING status after creating DNS records.

Common causes:

• Propagation delay. DNS changes can take up to 48 hours to propagate globally, though most providers propagate within minutes. Check propagation using dnschecker.org .
• Wrong record name. Ensure the TXT name is exactly _auris-verification.auth (not _auris-verification.auth.yourcompany.com — most providers append the zone automatically).
• Proxied record. If using Cloudflare, ensure the verification CNAME is set to “DNS Only” (gray cloud), not “Proxied” (orange cloud).
• TTL too high. If your previous record for this subdomain had a high TTL, the old value may be cached. Wait for the old TTL to expire.

Verify your records from the command line:

# Check TXT verification record
dig _auris-verification.auth.yourcompany.com TXT +short
 
# Check traffic CNAME
dig auth.yourcompany.com CNAME +short

SSL Certificate Not Provisioning

Symptom: Domain is ACTIVE but SSL status stays PENDING.

Common causes:

• Traffic CNAME missing. The SSL provisioner needs the traffic CNAME to be resolvable before it can issue a certificate. Make sure auth.yourcompany.com resolves to your-tenant.accounts.altovar.net.
• CAA records blocking issuance. If your domain has CAA DNS records, ensure letsencrypt.org is included as an allowed CA:

yourcompany.com.  IN  CAA  0 issue "letsencrypt.org"

SSL Certificate Renewal

SSL certificates are automatically renewed before expiry. No action is required. If renewal fails (e.g., DNS was changed), the domain status changes to Active with SSL status Expired. Fix the DNS and Auris will retry renewal automatically.

Deleting a Custom Domain

To remove a custom domain:

curl -X DELETE https://auth.yourdomain.com/api/custom-domains/cd_abc123 \
  -H "Authorization: Bearer $AURIS_ACCESS_TOKEN" \
  -H "x-tenant: your-tenant-id"

After deleting, update your SDK configuration to use the default Auris domain or another custom domain. Remember to clean up the DNS records at your provider.

Related Guides

• Hosted Login (PKCE) — Setting up the OAuth2 authorization code flow
• Enterprise SSO — SAML and OIDC federation for enterprise customers
• Branding — Complete branding customization guide