Custom Domains

Custom Domains allow you to use your own domain name for Auth0 login pages and endpoints instead of the default Auth0 domain.

List Custom Domains

Retrieves all custom domains configured in your tenant.

func (c *Client) List(
    ctx context.Context,
    request *management.ListCustomDomainsRequestParameters,
    opts ...option.RequestOption,
) (management.ListCustomDomainsResponseContent, error)

ctx

context.Context

required

Context for the request

request

*management.ListCustomDomainsRequestParameters

Query parameters:

Status - Filter by verification status
Type - Filter by domain type

opts

...option.RequestOption

Optional request options

Example

import (
    "context"
    "fmt"
    "log"

    "github.com/auth0/go-auth0/v2/management"
)

domains, err := client.Management.CustomDomains.List(
    context.TODO(),
    &management.ListCustomDomainsRequestParameters{},
)
if err != nil {
    log.Fatalf("Failed to list custom domains: %v", err)
}

for _, domain := range domains {
    fmt.Printf("Domain: %s (Status: %s)\n", domain.GetDomain(), domain.GetStatus())
}

Get Custom Domain

Retrieves configuration and status for a specific custom domain.

func (c *Client) Get(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) (*management.GetCustomDomainResponseContent, error)

ctx

context.Context

required

Context for the request

string

required

ID of the custom domain to retrieve

opts

...option.RequestOption

Optional request options

domain

*management.GetCustomDomainResponseContent

Returns the custom domain with properties:

CustomDomainID - Domain identifier
Domain - Domain name
Primary - Whether this is the primary domain
IsDefault - Whether this is the default custom domain
Status - Verification status
Type - Domain type (auth0_managed_certs or self_managed_certs)
Verification - Verification details
CustomClientIPHeader - Custom client IP header
TLSPolicy - TLS policy

Example

domain, err := client.Management.CustomDomains.Get(
    context.TODO(),
    "cd_1234567890",
)
if err != nil {
    log.Fatalf("Failed to get custom domain: %v", err)
}

fmt.Printf("Domain: %s\n", domain.GetDomain())
fmt.Printf("Status: %s\n", domain.GetStatus())

Create Custom Domain

Creates a new custom domain. The domain will need to be verified before it accepts requests.

func (c *Client) Create(
    ctx context.Context,
    request *management.CreateCustomDomainRequestContent,
    opts ...option.RequestOption,
) (*management.CreateCustomDomainResponseContent, error)

ctx

context.Context

required

Context for the request

request

*management.CreateCustomDomainRequestContent

required

The custom domain configuration:

Domain - Domain name (required)
Type - Domain type: “auth0_managed_certs” or “self_managed_certs” (required)
CustomClientIPHeader - Custom client IP header
TLSPolicy - TLS policy (e.g., “recommended”)

opts

...option.RequestOption

Optional request options

Example: Auth0 Managed Certificates

domain := &management.CreateCustomDomainRequestContent{
    Domain: "login.example.com",
    Type: "auth0_managed_certs",
    TLSPolicy: management.String("recommended"),
}

created, err := client.Management.CustomDomains.Create(context.TODO(), domain)
if err != nil {
    log.Fatalf("Failed to create custom domain: %v", err)
}

fmt.Printf("Domain ID: %s\n", created.GetCustomDomainID())
fmt.Printf("Verification method: %+v\n", created.Verification)

Example: Self-Managed Certificates

domain := &management.CreateCustomDomainRequestContent{
    Domain: "login.example.com",
    Type: "self_managed_certs",
}

created, err := client.Management.CustomDomains.Create(context.TODO(), domain)
if err != nil {
    log.Fatalf("Failed to create custom domain: %v", err)
}

Update Custom Domain

Updates a custom domain’s configuration.

func (c *Client) Update(
    ctx context.Context,
    id string,
    request *management.UpdateCustomDomainRequestContent,
    opts ...option.RequestOption,
) (*management.UpdateCustomDomainResponseContent, error)

ctx

context.Context

required

Context for the request

string

required

The ID of the custom domain to update

request

*management.UpdateCustomDomainRequestContent

required

The fields to update:

CustomClientIPHeader - Custom client IP header
TLSPolicy - TLS policy

opts

...option.RequestOption

Optional request options

Example

update := &management.UpdateCustomDomainRequestContent{
    CustomClientIPHeader: management.String("cf-connecting-ip"),
    TLSPolicy: management.String("recommended"),
}

updated, err := client.Management.CustomDomains.Update(
    context.TODO(),
    "cd_1234567890",
    update,
)
if err != nil {
    log.Fatalf("Failed to update custom domain: %v", err)
}

Delete Custom Domain

Deletes a custom domain and stops serving requests for it.

func (c *Client) Delete(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) error

ctx

context.Context

required

Context for the request

string

required

ID of the custom domain to delete

opts

...option.RequestOption

Optional request options

Example

err := client.Management.CustomDomains.Delete(
    context.TODO(),
    "cd_1234567890",
)
if err != nil {
    log.Fatalf("Failed to delete custom domain: %v", err)
}

Verify Custom Domain

Runs the verification process on a custom domain.

func (c *Client) Verify(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) (*management.VerifyCustomDomainResponseContent, error)

ctx

context.Context

required

Context for the request

string

required

ID of the custom domain to verify

opts

...option.RequestOption

Optional request options

Example

verified, err := client.Management.CustomDomains.Verify(
    context.TODO(),
    "cd_1234567890",
)
if err != nil {
    log.Fatalf("Failed to verify domain: %v", err)
}

fmt.Printf("Status: %s\n", verified.GetStatus())

Test Custom Domain

Runs the test process on a custom domain.

func (c *Client) Test(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) (*management.TestCustomDomainResponseContent, error)

ctx

context.Context

required

Context for the request

string

required

ID of the custom domain to test

opts

...option.RequestOption

Optional request options

Example

testResult, err := client.Management.CustomDomains.Test(
    context.TODO(),
    "cd_1234567890",
)
if err != nil {
    log.Fatalf("Domain test failed: %v", err)
}

fmt.Printf("Test passed: %+v\n", testResult)

Complete Example

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/auth0/go-auth0/v2/management"
)

func main() {
    client, err := management.New(
        context.TODO(),
        os.Getenv("AUTH0_DOMAIN"),
        management.WithClientCredentials(
            os.Getenv("AUTH0_CLIENT_ID"),
            os.Getenv("AUTH0_CLIENT_SECRET"),
        ),
    )
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    // Create a custom domain with Auth0 managed certificates
    domain := &management.CreateCustomDomainRequestContent{
        Domain: "login.example.com",
        Type: "auth0_managed_certs",
        TLSPolicy: management.String("recommended"),
    }

    created, err := client.Management.CustomDomains.Create(context.TODO(), domain)
    if err != nil {
        log.Fatalf("Failed to create custom domain: %v", err)
    }

    fmt.Printf("Created domain: %s\n", created.GetDomain())
    fmt.Printf("Domain ID: %s\n", created.GetCustomDomainID())
    
    // Print verification instructions
    if created.Verification != nil {
        fmt.Printf("\nVerification instructions:\n")
        fmt.Printf("Add the following DNS records:\n")
        fmt.Printf("%+v\n", created.Verification)
    }

    // Wait for DNS propagation, then verify
    fmt.Println("\nWaiting for DNS propagation...")
    time.Sleep(30 * time.Second)

    verified, err := client.Management.CustomDomains.Verify(
        context.TODO(),
        created.GetCustomDomainID(),
    )
    if err != nil {
        log.Printf("Verification failed (may need more time): %v", err)
    } else {
        fmt.Printf("Verification status: %s\n", verified.GetStatus())
    }
}

Domain Types

Auth0 Managed Certificates

Auth0 automatically manages SSL/TLS certificates:

Automatic certificate provisioning
Automatic certificate renewal
No certificate management required

Self-Managed Certificates

You provide and manage your own SSL/TLS certificates:

Full control over certificates
Bring your own CA
Manual certificate updates

Verification Status

pending - Awaiting verification
pending_verification - Verification in progress
ready - Domain verified and ready
failed - Verification failed

Best Practices

Use Auth0 Managed Certs - Simplifies certificate management
Test Before Production - Verify domain functionality before switching production traffic
Monitor Status - Regularly check domain status and certificate expiration
Configure DNS Properly - Ensure DNS records are correctly configured
Use Recommended TLS Policy - Keep TLS settings up to date with security best practices

Custom Domains Guide
Branding - Customize login pages
Tenant Settings - Configure tenant settings

Authentication API

Management API

Management Resources

Types & Utilities

List Custom Domains

Example

Get Custom Domain

Example

Create Custom Domain

Example: Auth0 Managed Certificates

Example: Self-Managed Certificates

Update Custom Domain

Example

Delete Custom Domain

Example

Verify Custom Domain

Example

Test Custom Domain

Example

Complete Example

Domain Types

Auth0 Managed Certificates

Self-Managed Certificates

Verification Status

Best Practices

Build docs developers (and LLMs) love

Authentication API

Management API

Management Resources

Types & Utilities

Documentation Index

​List Custom Domains

​Example

​Get Custom Domain

​Example

​Create Custom Domain

​Example: Auth0 Managed Certificates

​Example: Self-Managed Certificates

​Update Custom Domain

​Example

​Delete Custom Domain

​Example

​Verify Custom Domain

​Example

​Test Custom Domain

​Example

​Complete Example

​Domain Types

​Auth0 Managed Certificates

​Self-Managed Certificates

​Verification Status

​Best Practices

​Related Resources

Build docs developers (and LLMs) love

List Custom Domains

Example

Get Custom Domain

Example

Create Custom Domain

Example: Auth0 Managed Certificates

Example: Self-Managed Certificates

Update Custom Domain

Example

Delete Custom Domain

Example

Verify Custom Domain

Example

Test Custom Domain

Example

Complete Example

Domain Types

Auth0 Managed Certificates

Self-Managed Certificates

Verification Status

Best Practices

Related Resources