Migrating from v1 to v2

Please review this guide thoroughly to understand the changes required to migrate from go-auth0 v1 to go-auth0 v2

Overview

The Auth0 Go SDK v2 represents a complete rewrite of the SDK with the following major improvements:

Generated from OpenAPI

v2 is generated from Auth0’s OpenAPI specifications, ensuring consistency and accuracy

Improved Type Safety

Strongly typed request/response structures with proper enums and validation

Better Organization

Management APIs are organized into dedicated subpackages

Enhanced Developer Experience

Better IntelliSense support and clear method signatures

Breaking Changes

Module Name Change

The import path has changed from github.com/auth0/go-auth0 to github.com/auth0/go-auth0/v2.

import (
    "github.com/auth0/go-auth0"
    "github.com/auth0/go-auth0/management"
)

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

Package Structure Reorganization

v2 organizes management APIs into dedicated subpackages, replacing the monolithic structure of v1.

v1 Structure
v2 Structure

management/
├── client.go
├── user.go
├── connection.go
├── role.go
└── ... (all in root)

management/
├── clients/
│   └── client/
├── users/
│   └── client/
├── connections/
│   └── client/
├── roles/
│   └── client/
└── ... (organized by feature)

Generated Code and Type Safety

v2 uses generated code with strictly typed structures and enums, replacing the loosely typed approach of v1.

v1 (Loose Typing)
v2 (Strict Typing)

client := &management.Client{
    Name:    auth0.String("My App"),
    AppType: auth0.String("spa"),
    // Many fields are *string
}

client := &management.CreateClientRequestContent{
    Name:    "My App",
    AppType: &management.ClientAppTypeEnumSpa,
    // Proper enums and required fields
}

Management Client Initialization

The way you initialize and access management clients has changed significantly.

import "github.com/auth0/go-auth0/management"

mgmt, err := management.New(
    domain,
    management.WithClientCredentials(
        context.Background(),
        clientID,
        clientSecret,
    ),
)

// Access managers directly
client, err := mgmt.Client.Create(ctx, clientData)

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

mgmt, err := client.New(
    "your-tenant.auth0.com",
    option.WithClientCredentials(
        context.Background(),
        clientID,
        clientSecret,
    ),
)
if err != nil {
    // handle error
}

// Access through specific client managers
client, err := mgmt.Clients.Create(ctx, clientData)

API Method Signatures

Method signatures have been updated with more specific types and clearer parameter structures.

// Create a client
func (m *ClientManager) Create(
    ctx context.Context,
    c *Client,
    opts ...RequestOption,
) error

// List clients
func (m *ClientManager) List(
    ctx context.Context,
    opts ...RequestOption,
) (*ClientList, error)

// Create a client
func (c *Client) Create(
    ctx context.Context,
    request *management.CreateClientRequestContent,
    opts ...option.RequestOption,
) (*management.CreateClientResponseContent, error)

// List clients
func (c *Client) List(
    ctx context.Context,
    request *management.ListClientsRequest,
    opts ...option.RequestOption,
) (*management.ListClientsResponse, error)

Request and Response Types

v2 introduces specific request and response types for each operation.

// Single type for all operations
client := &management.Client{
    Name: auth0.String("My App"),
    // ... other fields
}

err := mgmt.Client.Create(ctx, client)

// Separate request and response types
createRequest := &management.CreateClientRequestContent{
    Name: "My App",
    // ... other fields
}

response, err := mgmt.Clients.Create(ctx, createRequest)
// response is *management.CreateClientResponseContent

Migration Steps

Step 1: Update Dependencies

Update your go.mod file:

# Remove old dependency
go mod edit -droprequire github.com/auth0/go-auth0

# Add new dependency
go get github.com/auth0/go-auth0/v2

Step 2: Update Imports

Replace all imports:

import "github.com/auth0/go-auth0/management"

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

Step 3: Update Client Initialization

mgmt, err := management.New(
    domain,
    management.WithClientCredentials(ctx, clientID, clientSecret),
)

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

Step 4: Update API Calls

Update your API calls to use the new structure and types:

client := &management.Client{
    Name: auth0.String("My App"),
}
err := mgmt.Client.Create(ctx, client)

request := &management.CreateClientRequestContent{
    Name: "My App",
}
response, err := mgmt.Clients.Create(ctx, request)

Examples

Client Management

package main

import (
    "context"
    "github.com/auth0/go-auth0"
    "github.com/auth0/go-auth0/management"
)

func main() {
    mgmt, err := management.New(
        "your-domain.auth0.com",
        management.WithClientCredentials(
            context.Background(),
            "client-id",
            "client-secret",
        ),
    )
    if err != nil {
        panic(err)
    }

    // Create client
    client := &management.Client{
        Name:    auth0.String("My App"),
        AppType: auth0.String("spa"),
        Callbacks: &[]string{
            "http://localhost:3000/callback",
        },
    }

    err = mgmt.Client.Create(context.Background(), client)
    if err != nil {
        panic(err)
    }

    // List clients
    clients, err := mgmt.Client.List(context.Background())
    if err != nil {
        panic(err)
    }
}

package main

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

func main() {
    mgmt, err := client.New(
        "your-domain.auth0.com",
        option.WithClientCredentials(
            context.Background(),
            "client-id",
            "client-secret",
        ),
    )
    if err != nil {
        panic(err)
    }

    // Create client
    request := &management.CreateClientRequestContent{
        Name:    "My App",
        AppType: &management.ClientAppTypeEnumSpa,
        Callbacks: []string{
            "http://localhost:3000/callback",
        },
    }

    response, err := mgmt.Clients.Create(context.Background(), request)
    if err != nil {
        panic(err)
    }

    // List clients
    listRequest := &management.ListClientsRequest{}
    clients, err := mgmt.Clients.List(context.Background(), listRequest)
    if err != nil {
        panic(err)
    }
}

User Management

// Create user
user := &management.User{
    Email:      auth0.String("[email protected]"),
    Connection: auth0.String("Username-Password-Authentication"),
    Password:   auth0.String("password123"),
}

err := mgmt.User.Create(ctx, user)

// List users
users, err := mgmt.User.List(ctx)

// Create user
request := &management.CreateUserRequestContent{
    Email:      "[email protected]",
    Connection: "Username-Password-Authentication",
    Password:   management.String("password123"),
}

response, err := mgmt.Users.Create(ctx, request)

// List users
listRequest := &management.ListUsersRequest{}
users, err := mgmt.Users.List(ctx, listRequest)

Connection Management

// Create connection
connection := &management.Connection{
    Name:     auth0.String("my-database"),
    Strategy: auth0.String("auth0"),
    Options: &management.ConnectionOptions{
        BruteForceProtection: auth0.Bool(true),
    },
}

err := mgmt.Connection.Create(ctx, connection)

// Create connection
request := &management.CreateConnectionRequestContent{
    Name:     "my-database",
    Strategy: management.ConnectionStrategyEnumAuth0,
    Options: &management.ConnectionOptions{
        BruteForceProtection: management.Bool(true),
    },
}

response, err := mgmt.Connections.Create(ctx, request)

Authentication Package

The authentication package remains largely unchanged between v1 and v2. You can continue using it with minimal modifications:

// Both v1 and v2 support similar authentication patterns
import "github.com/auth0/go-auth0/v2/authentication"

auth, err := authentication.New(
    context.Background(),
    "your-domain.auth0.com",
    authentication.WithClientID("client-id"),
    authentication.WithClientSecret("client-secret"),
)

Additional Notes

Context Requirement

All v2 methods require a context.Context as the first parameter

Option Pattern

v2 uses a consistent option pattern for configuration

Error Handling

Error types may have changed - review your error handling logic

Pagination

List methods now return specific response types with pagination information

Type Safety

Take advantage of the improved type safety by using the provided enums and constants

Troubleshooting

Common Issues

Import Errors

Make sure to update all import statements to use the new module path github.com/auth0/go-auth0/v2

Type Mismatches

Use the new strongly-typed structures instead of generic map types. Replace pointer string helpers with direct values or the new helper functions.

Method Not Found

Check the new package structure - methods may have moved to subpackages. For example, mgmt.Client is now mgmt.Clients

Initialization Errors

Use the new client initialization pattern with options from the option package

Getting Help

API Reference

Check the API reference documentation

GitHub Examples

Review examples in the repository

GitHub Issues

Open an issue for migration problems

This migration guide covers the major changes needed to upgrade from go-auth0 v1 to go-auth0 v2. While the changes are significant, the improved type safety and organization make the SDK more robust and easier to use.

Get Started

Core Concepts

Guides

Advanced

Migration

Migrating from v1 to v2

Overview

Generated from OpenAPI

Improved Type Safety

Better Organization

Enhanced Developer Experience

Breaking Changes

Module Name Change

Package Structure Reorganization

Generated Code and Type Safety

Management Client Initialization

API Method Signatures

Request and Response Types

Migration Steps

Step 1: Update Dependencies

Step 2: Update Imports

Step 3: Update Client Initialization

Step 4: Update API Calls

Examples

Client Management

User Management

Connection Management

Authentication Package

Additional Notes

Troubleshooting

Common Issues

Getting Help

API Reference

GitHub Examples

GitHub Issues

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Migration

​Overview

Generated from OpenAPI

Improved Type Safety

Better Organization

Enhanced Developer Experience

​Breaking Changes

​Module Name Change

​Package Structure Reorganization

​Generated Code and Type Safety

​Management Client Initialization

​API Method Signatures

​Request and Response Types

​Migration Steps

​Step 1: Update Dependencies

​Step 2: Update Imports

​Step 3: Update Client Initialization

​Step 4: Update API Calls

​Examples

​Client Management

​User Management

​Connection Management

​Authentication Package

​Additional Notes

​Troubleshooting

​Common Issues

​Getting Help

API Reference

GitHub Examples

GitHub Issues

Build docs developers (and LLMs) love

Overview

Breaking Changes

Module Name Change

Package Structure Reorganization

Generated Code and Type Safety

Management Client Initialization

API Method Signatures

Request and Response Types

Migration Steps

Step 1: Update Dependencies

Step 2: Update Imports

Step 3: Update Client Initialization

Step 4: Update API Calls

Examples

Client Management

User Management

Connection Management

Authentication Package

Additional Notes

Troubleshooting

Common Issues

Getting Help