Skip to main content
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
​
id
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
​
id
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
​
id
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
​
id
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
​
id
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us