Skip to main content
The SDK provides fine-grained control over individual requests through request options. These options can be passed to any API method to customize behavior on a per-request basis.

​
Available Request Options

All request options are available in the option package for Management API calls: 
import "github.com/auth0/go-auth0/v2/management/option"

​
Custom Headers

Add custom HTTP headers to your requests: 
import "net/http"

// Add custom headers to a request
clients, err := mgmt.Clients.List(
    ctx,
    &management.ListClientsRequestParameters{},
    option.WithHTTPHeader(http.Header{
        "X-Custom-Header": []string{"custom-value"},
        "X-Request-ID":    []string{"req-123"},
        "X-Source":        []string{"go-sdk"},
    }),
)
Custom headers are useful for:
  • Request tracing and correlation IDs
  • A/B testing variants
  • Feature flags
  • Custom authentication schemes

​
Query Parameters

Add or override query parameters: 
import "net/url"

// Add query parameters to filter response fields
queryParams := url.Values{}
queryParams.Set("include_fields", "client_id,name,app_type")
queryParams.Set("exclude_fields", "client_secret")

clients, err := mgmt.Clients.List(
    ctx,
    &management.ListClientsRequestParameters{},
    option.WithQueryParameters(queryParams),
)

​
Common Use Cases

// Include only specific fields
queryParams := url.Values{}
queryParams.Set("fields", "client_id,name,callbacks")
queryParams.Set("include_fields", "true")

client, err := mgmt.Clients.Read(
    ctx,
    clientID,
    option.WithQueryParameters(queryParams),
)

​
Body Properties

Add custom properties to request bodies: 
// Add custom fields not in the SDK types
bodyProps := map[string]interface{}{
    "custom_field": "custom_value",
    "integration_metadata": map[string]interface{}{
        "source":      "terraform",
        "environment": "production",
        "team":        "platform",
    },
}

client, err := mgmt.Clients.Create(
    ctx,
    createRequest,
    option.WithBodyProperties(bodyProps),
)

​
Setting Fields to Null

Use WithBodyProperties to explicitly set fields to null: 
// Set description and logo_uri to null
_, err := mgmt.Clients.Update(
    ctx,
    clientID,
    &management.UpdateClientRequestContent{
        Name: management.String("Updated App Name"),
    },
    option.WithBodyProperties(map[string]interface{}{
        "description":     nil, // Sets description to null
        "logo_uri":        nil, // Sets logo_uri to null
        "custom_metadata": nil, // Sets custom_metadata to null
    }),
)

​
Advanced Configuration

// Add complex nested configuration
customBodyProps := map[string]interface{}{
    "custom_domain_verified": true,
    "advanced_settings": map[string]interface{}{
        "custom_login_page":        true,
        "universal_login_branding": true,
        "password_policy":          "excellent",
    },
    "integration_settings": map[string]interface{}{
        "webhook_endpoints": []string{
            "https://api.example.com/webhook",
            "https://backup.example.com/webhook",
        },
        "retry_policy": "exponential_backoff",
        "timeout":      30,
    },
}

client, err := mgmt.Clients.Create(
    ctx,
    createRequest,
    option.WithBodyProperties(customBodyProps),
)

​
Retry Configuration

Configure the number of retry attempts for individual requests: 
// Retry up to 5 times for important operations
users, err := mgmt.Users.List(
    ctx,
    &management.ListUsersRequestParameters{},
    option.WithMaxAttempts(5),
)
The SDK automatically retries failed requests with exponential backoff. Use WithMaxAttempts to increase retries for critical operations or decrease for non-critical ones.

​
Combining Multiple Options

You can pass multiple options to a single request: 
import (
    "net/http"
    "net/url"
)

// Combine headers, query params, and retry config
queryParams := url.Values{}
queryParams.Set("fields", "client_id,name")

clients, err := mgmt.Clients.List(
    ctx,
    &management.ListClientsRequestParameters{
        AppType: management.String("spa"),
        PerPage: management.Int(50),
    },
    option.WithHTTPHeader(http.Header{
        "X-Request-ID": []string{"req-456"},
    }),
    option.WithQueryParameters(queryParams),
    option.WithMaxAttempts(3),
)

​
Client-Level Options

Some options can be set at the client level during initialization and apply to all requests.

​
Authentication Options

mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithClientCredentials(
        context.Background(),
        "YOUR_CLIENT_ID",
        "YOUR_CLIENT_SECRET",
    ),
)

​
Debug Mode

Enable debug logging for all requests: 
mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithClientCredentials(
        context.Background(),
        "YOUR_CLIENT_ID",
        "YOUR_CLIENT_SECRET",
    ),
    option.WithDebug(true),
)

​
Custom User Agent

Set a custom User-Agent header: 
mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithClientCredentials(
        context.Background(),
        "YOUR_CLIENT_ID",
        "YOUR_CLIENT_SECRET",
    ),
    option.WithUserAgent("MyApp/1.0 (Go SDK)"),
)

​
Custom HTTP Client

Provide your own HTTP client with custom configuration: 
import (
    "net/http"
    "time"
)

customHTTPClient := &http.Client{
    Timeout: 30 * time.Second,
    Transport: &http.Transport{
        MaxIdleConns:        100,
        MaxIdleConnsPerHost: 10,
        IdleConnTimeout:     90 * time.Second,
    },
}

mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithClientCredentials(
        context.Background(),
        "YOUR_CLIENT_ID",
        "YOUR_CLIENT_SECRET",
    ),
    option.WithHTTPClient(customHTTPClient),
)

​
Custom Domain

Set a custom domain header: 
mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithClientCredentials(
        context.Background(),
        "YOUR_CLIENT_ID",
        "YOUR_CLIENT_SECRET",
    ),
    option.WithCustomDomainHeader("login.example.com"),
)

​
Auth0 Client Info

Customize or disable the Auth0-Client header: 
mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithClientCredentials(
        context.Background(),
        "YOUR_CLIENT_ID",
        "YOUR_CLIENT_SECRET",
    ),
    option.WithAuth0ClientEnvEntry("my-app", "1.0.0"),
)

​
Real-World Examples

​
Request Tracing

Implement distributed tracing with correlation IDs: 
import (
    "net/http"
    "github.com/google/uuid"
)

func createUserWithTracing(ctx context.Context, mgmt *client.Client, email string) error {
    // Generate correlation ID
    correlationID := uuid.New().String()

    createRequest := &management.CreateUserRequestContent{
        Email:      email,
        Connection: "Username-Password-Authentication",
    }

    user, err := mgmt.Users.Create(
        ctx,
        createRequest,
        option.WithHTTPHeader(http.Header{
            "X-Correlation-ID": []string{correlationID},
            "X-Service":        []string{"user-service"},
        }),
    )
    if err != nil {
        log.Printf("Error creating user [%s]: %v", correlationID, err)
        return err
    }

    log.Printf("Created user [%s]: %s", correlationID, *user.GetUserID())
    return nil
}

​
Conditional Updates

Update only if certain conditions are met: 
import "net/http"

func updateClientIfNotModified(ctx context.Context, mgmt *client.Client, clientID, etag string) error {
    updateRequest := &management.UpdateClientRequestContent{
        Description: management.String("Updated description"),
    }

    _, err := mgmt.Clients.Update(
        ctx,
        clientID,
        updateRequest,
        option.WithHTTPHeader(http.Header{
            "If-Match": []string{etag},
        }),
    )

    return err
}

​
Bulk Operations with Custom Retry

Handle bulk operations with increased retry attempts: 
func bulkCreateUsers(ctx context.Context, mgmt *client.Client, emails []string) error {
    for _, email := range emails {
        createRequest := &management.CreateUserRequestContent{
            Email:      email,
            Connection: "Username-Password-Authentication",
        }

        // Use higher retry count for bulk operations
        _, err := mgmt.Users.Create(
            ctx,
            createRequest,
            option.WithMaxAttempts(5),
        )
        if err != nil {
            log.Printf("Failed to create user %s: %v", email, err)
            continue
        }

        log.Printf("Created user: %s", email)
    }

    return nil
}

​
Best Practices

Always include correlation or request IDs in headers for easier debugging:
option.WithHTTPHeader(http.Header{
    "X-Request-ID": []string{requestID},
})
Use higher retry counts for critical operations, lower for less important ones:
// Critical: user authentication
option.WithMaxAttempts(5)

// Non-critical: analytics tracking
option.WithMaxAttempts(1)
Only use the options you need for a request to keep code clean:
// Good: only necessary options
mgmt.Users.List(ctx, listRequest, option.WithMaxAttempts(3))

// Avoid: unnecessary options
mgmt.Users.List(
    ctx,
    listRequest,
    option.WithMaxAttempts(3),
    option.WithHTTPHeader(http.Header{}), // Empty header
    option.WithQueryParameters(url.Values{}), // Empty params
)
When working with fields not yet in the SDK:
option.WithBodyProperties(map[string]interface{}{
    "new_api_field": "value",
})

​
Next Steps

User Management

Apply request options to user operations

Client Management

Apply request options to client operations

Build docs developers (and LLMs) love

Get started for freeTalk to us