Quick start

This guide walks you through building a complete integration with both the Authentication and Management APIs. You’ll learn how to authenticate users, manage resources, and handle common operations.

Before you begin

Make sure you’ve completed the installation and have your Auth0 credentials ready:

Domain (e.g., example.us.auth0.com)
Client ID and Client Secret for Authentication API
Client ID and Client Secret for Management API (with appropriate scopes)

Authentication API quick start

The Authentication API enables user-facing authentication flows.

Initialize the client

Create an authentication client with your credentials:

package main

import (
    "context"
    "log"
    
    "github.com/auth0/go-auth0/v2/authentication"
    "github.com/auth0/go-auth0/v2/authentication/database"
    "github.com/auth0/go-auth0/v2/authentication/oauth"
)

func main() {
    // Get these from your Auth0 Application Dashboard
    domain := "example.us.auth0.com"
    clientID := "EXAMPLE_16L9d34h0qe4NVE6SaHxZEid"
    clientSecret := "EXAMPLE_XSQGmnt8JdXs23407hrK6XXXXXXX"
    
    // Initialize a new client
    authAPI, err := authentication.New(
        context.TODO(), // Replace with a Context that better suits your usage
        domain,
        authentication.WithClientID(clientID),
        authentication.WithClientSecret(clientSecret), // Optional depending on the grants used
    )
    if err != nil {
        log.Fatalf("failed to initialize the auth0 authentication API client: %+v", err)
    }
    
    // Now we can interact with the Auth0 Authentication API
}

The context package can be used to pass cancellation signals and deadlines. If there is no context available, use context.Background().

Create a new user account with the Database API:

// Sign up a user
userData := database.SignupRequest{
    Connection: "Username-Password-Authentication",
    Username:   "mytestaccount",
    Password:   "mypassword",
    Email:      "mytestaccount@example.com",
}

createdUser, err := authAPI.Database.Signup(context.Background(), userData)
if err != nil {
    log.Fatalf("failed to sign user up: %+v", err)
}

log.Printf("Created user: %s", createdUser.Email)

Authenticate with OAuth

Implement OAuth authentication flows:

// Login using OAuth Authorization Code with PKCE
tokenSet, err := authAPI.OAuth.LoginWithAuthCodeWithPKCE(
    context.Background(),
    oauth.LoginWithAuthCodeWithPKCERequest{
        Code:         "test-code",
        CodeVerifier: "test-code-verifier",
    },
    oauth.IDTokenValidationOptions{},
)
if err != nil {
    log.Fatalf("failed to retrieve tokens: %+v", err)
}

log.Printf("Access token: %s", tokenSet.AccessToken)

Get user information

Retrieve user profile information using an access token:

// Get user info with an access token
userInfo, err := authAPI.UserInfo(context.Background(), tokenSet.AccessToken)
if err != nil {
    log.Fatalf("failed to get user info: %+v", err)
}

log.Printf("User email: %s", userInfo.Email)
log.Printf("User ID: %s", userInfo.Sub)

Complete Authentication API example

Here’s the complete code:

package main

import (
    "context"
    "log"
    
    "github.com/auth0/go-auth0/v2/authentication"
    "github.com/auth0/go-auth0/v2/authentication/database"
    "github.com/auth0/go-auth0/v2/authentication/oauth"
)

func main() {
    // Get these from your Auth0 Application Dashboard
    domain := "example.us.auth0.com"
    clientID := "EXAMPLE_16L9d34h0qe4NVE6SaHxZEid"
    clientSecret := "EXAMPLE_XSQGmnt8JdXs23407hrK6XXXXXXX"
    
    // Initialize a new client
    authAPI, err := authentication.New(
        context.TODO(),
        domain,
        authentication.WithClientID(clientID),
        authentication.WithClientSecret(clientSecret),
    )
    if err != nil {
        log.Fatalf("failed to initialize the auth0 authentication API client: %+v", err)
    }
    
    // Sign up a user
    userData := database.SignupRequest{
        Connection: "Username-Password-Authentication",
        Username:   "mytestaccount",
        Password:   "mypassword",
        Email:      "mytestaccount@example.com",
    }
    
    createdUser, err := authAPI.Database.Signup(context.Background(), userData)
    if err != nil {
        log.Fatalf("failed to sign user up: %+v", err)
    }
    
    log.Printf("Created user: %s", createdUser.Email)
    
    // Login using OAuth grants
    tokenSet, err := authAPI.OAuth.LoginWithAuthCodeWithPKCE(
        context.Background(),
        oauth.LoginWithAuthCodeWithPKCERequest{
            Code:         "test-code",
            CodeVerifier: "test-code-verifier",
        },
        oauth.IDTokenValidationOptions{},
    )
    if err != nil {
        log.Fatalf("failed to retrieve tokens: %+v", err)
    }
    
    log.Printf("Successfully authenticated!")
}

Management API quick start

The Management API is designed for backend services and administrative operations.

Initialize the client

Create a management client using client credentials:

package main

import (
    "context"
    "log"
    
    "github.com/auth0/go-auth0/v2/management"
    "github.com/auth0/go-auth0/v2/management/client"
    "github.com/auth0/go-auth0/v2/management/option"
)

func main() {
    // Initialize your client with a domain and token
    mgmt, err := client.New(
        "example.us.auth0.com",
        option.WithClientCredentials(
            context.Background(),
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    if err != nil {
        log.Fatalf("Failed to create management client: %v", err)
    }
    
    // Now we can interact with the Auth0 Management API
}

Replace context.Background() with a Context that better suits your usage, such as one with cancellation or timeout capabilities.

Create a new application

Create a Single Page Application in Auth0:

ctx := context.Background()

// Create a new client application
createRequest := &management.CreateClientRequestContent{
    Name:    "My Go SDK App",
    AppType: &management.ClientAppTypeEnumSpa,
    Callbacks: []string{
        "http://localhost:3000/callback",
        "https://myapp.com/callback",
    },
    AllowedOrigins: []string{
        "http://localhost:3000",
        "https://myapp.com",
    },
    OidcConformant: management.Bool(true),
}

clientResponse, err := mgmt.Clients.Create(ctx, createRequest)
if err != nil {
    log.Fatalf("Error creating client: %v", err)
}

log.Printf("Created client: %s (ID: %s)",
    *clientResponse.GetName(),
    *clientResponse.GetClientID(),
)

List applications

Retrieve all Single Page Applications:

// List all SPA clients
listRequest := &management.ListClientsRequestParameters{
    AppType: management.String("spa"),
    Fields:  management.String("client_id,name,app_type"),
    IncludeFields: management.Bool(true),
    PerPage: management.Int(10),
}

clientsPage, err := mgmt.Clients.List(ctx, listRequest)
if err != nil {
    log.Fatalf("Error listing clients: %v", err)
}

log.Println("SPA Clients:")
for _, client := range clientsPage.Results {
    log.Printf("- %s (%s)", *client.GetName(), *client.GetClientID())
}

Update an application

Modify an existing application:

// Update the client
updateRequest := &management.UpdateClientRequestContent{
    Description: management.String("Updated description for my app"),
    LogoURI:     management.String("https://example.com/logo.png"),
}

updatedClient, err := mgmt.Clients.Update(
    ctx,
    *clientResponse.GetClientID(),
    updateRequest,
)
if err != nil {
    log.Fatalf("Error updating client: %v", err)
}

log.Printf("Updated client description: %s",
    *updatedClient.GetDescription(),
)

Complete Management API example

Here’s the complete code:

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/auth0/go-auth0/v2/management"
    "github.com/auth0/go-auth0/v2/management/client"
    "github.com/auth0/go-auth0/v2/management/option"
)

func main() {
    // Initialize management client
    mgmt, err := client.New(
        "your-tenant.auth0.com",
        option.WithClientCredentials(
            context.Background(),
            "YOUR_CLIENT_ID",
            "YOUR_CLIENT_SECRET",
        ),
    )
    if err != nil {
        log.Fatalf("Error creating management client: %v", err)
    }
    
    ctx := context.Background()
    
    // Create a new client application
    createRequest := &management.CreateClientRequestContent{
        Name:    "My Go SDK v2 App",
        AppType: &management.ClientAppTypeEnumSpa,
        Callbacks: []string{
            "http://localhost:3000/callback",
            "https://myapp.com/callback",
        },
        AllowedOrigins: []string{
            "http://localhost:3000",
            "https://myapp.com",
        },
        OidcConformant: management.Bool(true),
        JwtConfiguration: &management.ClientJwtConfiguration{
            Algorithm:         management.String("RS256"),
            LifetimeInSeconds: management.Int(3600),
        },
    }
    
    clientResponse, err := mgmt.Clients.Create(ctx, createRequest)
    if err != nil {
        log.Fatalf("Error creating client: %v", err)
    }
    
    fmt.Printf("Created client: %s (ID: %s)\n",
        *clientResponse.GetName(),
        *clientResponse.GetClientID(),
    )
    
    // List all SPA clients
    listRequest := &management.ListClientsRequestParameters{
        AppType: management.String("spa"),
        Fields:  management.String("client_id,name,app_type,callbacks"),
        IncludeFields: management.Bool(true),
        PerPage: management.Int(10),
    }
    
    clientsPage, err := mgmt.Clients.List(ctx, listRequest)
    if err != nil {
        log.Fatalf("Error listing clients: %v", err)
    }
    
    fmt.Println("\nSPA Clients:")
    iterator := clientsPage.Iterator()
    for iterator.Next(ctx) {
        client := iterator.Current()
        fmt.Printf("- %s (%s)\n", *client.GetName(), *client.GetClientID())
    }
    
    if iterator.Err() != nil {
        log.Fatalf("Error iterating clients: %v", iterator.Err())
    }
    
    // Update the client
    updateRequest := &management.UpdateClientRequestContent{
        Description: management.String("Updated description for my app"),
        LogoURI:     management.String("https://example.com/logo.png"),
    }
    
    updatedClient, err := mgmt.Clients.Update(
        ctx,
        *clientResponse.GetClientID(),
        updateRequest,
    )
    if err != nil {
        log.Fatalf("Error updating client: %v", err)
    }
    
    fmt.Printf("Updated client description: %s\n",
        *updatedClient.GetDescription(),
    )
}

Working with pagination

The SDK provides built-in pagination support with iterators for seamless data retrieval.

Using the iterator pattern

// Create a request with pagination settings
listRequest := &management.ListUsersRequestParameters{
    Search:  management.String("email:\"*@example.com\""),
    PerPage: management.Int(50),
}

usersPage, err := mgmt.Users.List(ctx, listRequest)
if err != nil {
    log.Fatalf("Error listing users: %v", err)
}

// Use the iterator to automatically paginate through all results
iterator := usersPage.Iterator()
for iterator.Next(ctx) {
    user := iterator.Current()
    fmt.Printf("User: %s\n", *user.GetEmail())
}

if iterator.Err() != nil {
    log.Fatalf("Error during iteration: %v", iterator.Err())
}

Manual pagination

page := 0

for {
    listRequest := &management.ListClientsRequestParameters{
        Page:    management.Int(page),
        PerPage: management.Int(25),
    }
    
    clientsPage, err := mgmt.Clients.List(ctx, listRequest)
    if err != nil {
        log.Fatalf("Error listing clients: %v", err)
    }
    
    // Process current page
    for _, client := range clientsPage.Results {
        fmt.Printf("Client: %s\n", *client.GetName())
    }
    
    // Try to get next page
    nextPage, err := clientsPage.GetNextPage(ctx)
    if err != nil {
        // No more pages
        break
    }
    
    clientsPage = nextPage
    page++
}

Error handling

Always check for errors and handle them appropriately:

import (
    "errors"
    "fmt"
)

// Basic error handling
clients, err := mgmt.Clients.List(ctx, &management.ListClientsRequestParameters{})
if err != nil {
    fmt.Printf("Error listing clients: %v\n", err)
    return
}

// Handle authentication-specific errors
tokens, err := authAPI.OAuth.LoginWithPassword(
    context.Background(),
    oauth.LoginWithPasswordRequest{
        Username: "test@example.com",
        Password: "hunter2",
    },
    oauth.IDTokenValidationOptions{},
)
if err != nil {
    if aerr, ok := err.(*authentication.Error); ok {
        if aerr.Err == "mfa_required" {
            // Handle MFA requirement
            fmt.Println("MFA is required")
        }
    }
    return
}

Alternative authentication methods

The SDK supports multiple authentication approaches:

// Using a pre-acquired static token
mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithToken("YOUR_ACCESS_TOKEN"),
)

Next steps

Now that you have a working integration, explore more advanced features:

User management

Learn how to create, search, and manage users

Pagination

Master pagination with iterators and checkpoint pagination

Request options

Customize requests with headers, parameters, and retry logic

Advanced topics

Explore custom token sources and advanced patterns

Get Started

Core Concepts

Guides

Advanced

Migration

Before you begin

Authentication API quick start

Complete Authentication API example

Management API quick start

Complete Management API example

Using the iterator pattern

Error handling

Alternative authentication methods

Next steps

User management

Pagination

Request options

Advanced topics

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Migration

Documentation Index

​Before you begin

​Authentication API quick start

​Complete Authentication API example

​Management API quick start

​Complete Management API example

​Working with pagination

​Using the iterator pattern

​Manual pagination

​Error handling

​Alternative authentication methods

​Next steps

User management

Pagination

Request options

Advanced topics

Build docs developers (and LLMs) love

Before you begin

Authentication API quick start

Complete Authentication API example

Management API quick start

Complete Management API example

Working with pagination

Using the iterator pattern

Manual pagination

Error handling

Alternative authentication methods

Next steps