User Management Guide

The User Management API provides comprehensive methods for managing users in your Auth0 tenant.

Prerequisites

Ensure you have initialized a management client:

import (
    "context"
    "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(),
        "YOUR_CLIENT_ID",
        "YOUR_CLIENT_SECRET",
    ),
)

Creating Users

Basic User
User with Metadata
User with Profile
User Without Password

Create a user with email and password:

createRequest := &management.CreateUserRequestContent{
    Email:      "user@example.com",
    Connection: "Username-Password-Authentication",
    Password:   management.String("SecurePassword123!"),
}

user, err := mgmt.Users.Create(ctx, createRequest)
if err != nil {
    return err
}

fmt.Printf("Created user: %s (ID: %s)\n",
    *user.GetEmail(),
    *user.GetUserID(),
)

Create a user with custom metadata:

createRequest := &management.CreateUserRequestContent{
    Email:      "user@example.com",
    Connection: "Username-Password-Authentication",
    Password:   management.String("SecurePassword123!"),
    UserMetadata: map[string]interface{}{
        "preference": "email",
        "plan":       "premium",
        "tier":       "gold",
    },
    AppMetadata: map[string]interface{}{
        "role":        "user",
        "permissions": []string{"read:profile", "update:profile"},
        "tenant_id":   "tenant_123",
    },
}

user, err := mgmt.Users.Create(ctx, createRequest)

Create a user with full profile information:

createRequest := &management.CreateUserRequestContent{
    Email:       "john.doe@example.com",
    Connection:  "Username-Password-Authentication",
    Password:    management.String("SecurePassword123!"),
    GivenName:   management.String("John"),
    FamilyName:  management.String("Doe"),
    Name:        management.String("John Doe"),
    Nickname:    management.String("johnd"),
    Picture:     management.String("https://example.com/photo.jpg"),
    PhoneNumber: management.String("+1234567890"),
    UserMetadata: map[string]interface{}{
        "timezone":        "America/New_York",
        "language":        "en",
        "newsletter":      true,
        "marketing_opted": false,
    },
}

user, err := mgmt.Users.Create(ctx, createRequest)

Create a user for social/enterprise connections:

createRequest := &management.CreateUserRequestContent{
    Email:      "user@example.com",
    Connection: "google-oauth2",
    // No password needed for social connections
}

user, err := mgmt.Users.Create(ctx, createRequest)

User Metadata vs App Metadata

User Metadata: Editable by users, stores user preferences and non-sensitive data
App Metadata: Only editable via Management API, stores sensitive data like roles and permissions

Reading Users

Get a Single User

userID := "auth0|123456789"

user, err := mgmt.Users.Read(ctx, userID)
if err != nil {
    return err
}

fmt.Printf("User: %s\n", *user.GetEmail())
fmt.Printf("Created: %s\n", *user.GetCreatedAt())
fmt.Printf("Email Verified: %v\n", *user.GetEmailVerified())

List All Users

listRequest := &management.ListUsersRequestParameters{
    PerPage: management.Int(50),
}

usersPage, err := mgmt.Users.List(ctx, listRequest)
if err != nil {
    return err
}

for _, user := range usersPage.Results {
    fmt.Printf("User: %s\n", *user.GetEmail())
}

Updating Users

Update Profile
Update Metadata
Verify Email
Block/Unblock User

Update basic profile information:

updateRequest := &management.UpdateUserRequestContent{
    GivenName:  management.String("Jane"),
    FamilyName: management.String("Smith"),
    Name:       management.String("Jane Smith"),
    Nickname:   management.String("janes"),
    Picture:    management.String("https://example.com/new-photo.jpg"),
}

user, err := mgmt.Users.Update(ctx, userID, updateRequest)

Update user or app metadata:

updateRequest := &management.UpdateUserRequestContent{
    UserMetadata: map[string]interface{}{
        "preference":  "sms",
        "plan":        "enterprise",
        "last_login":  time.Now().Format(time.RFC3339),
    },
    AppMetadata: map[string]interface{}{
        "role":        "admin",
        "permissions": []string{"read:*", "write:*", "delete:*"},
    },
}

user, err := mgmt.Users.Update(ctx, userID, updateRequest)

Mark a user’s email as verified:

updateRequest := &management.UpdateUserRequestContent{
    EmailVerified: management.Bool(true),
}

user, err := mgmt.Users.Update(ctx, userID, updateRequest)

Block or unblock a user:

// Block user
updateRequest := &management.UpdateUserRequestContent{
    Blocked: management.Bool(true),
}

user, err := mgmt.Users.Update(ctx, userID, updateRequest)

// Unblock user
updateRequest = &management.UpdateUserRequestContent{
    Blocked: management.Bool(false),
}

user, err = mgmt.Users.Update(ctx, userID, updateRequest)

Searching Users

Auth0 provides powerful search capabilities using Lucene query syntax.

Search by Email

searchRequest := &management.ListUsersRequestParameters{
    Search:  management.String("email:\"*@example.com\""),
    PerPage: management.Int(25),
}

usersPage, err := mgmt.Users.List(ctx, searchRequest)

Search with Multiple Criteria

searchRequest := &management.ListUsersRequestParameters{
    Search: management.String("email:\"*@company.com\""),
    Sort:   management.String("created_at:1"),
}

Sorting Results

searchRequest := &management.ListUsersRequestParameters{
    Search:  management.String("email:\"*@example.com\""),
    Sort:    management.String("created_at:-1"), // -1 for descending
    PerPage: management.Int(50),
}

Sort options:

created_at:1 - Oldest first
created_at:-1 - Newest first
last_login:1 - Least recently logged in first
last_login:-1 - Most recently logged in first

Pagination

Use the iterator pattern for efficient pagination:

searchRequest := &management.ListUsersRequestParameters{
    Search:  management.String("email:\"*@example.com\""),
    PerPage: management.Int(50),
}

usersPage, err := mgmt.Users.List(ctx, searchRequest)
if err != nil {
    return err
}

iterator := usersPage.Iterator()
for iterator.Next(ctx) {
    user := iterator.Current()
    fmt.Printf("User: %s (Created: %s)\n",
        *user.GetEmail(),
        *user.GetCreatedAt(),
    )
}

if iterator.Err() != nil {
    return iterator.Err()
}

Deleting Users

err := mgmt.Users.Delete(ctx, userID)
if err != nil {
    return err
}

fmt.Printf("Deleted user: %s\n", userID)

Deleting a user is permanent and cannot be undone. Consider blocking users instead if you need to preserve data.

Working with User Roles

Assign Roles to User

roleIDs := []string{"rol_abc123", "rol_xyz789"}

err := mgmt.Users.AssignRoles(ctx, userID, roleIDs)
if err != nil {
    return err
}

List User Roles

rolesPage, err := mgmt.Users.Roles(ctx, userID, nil)
if err != nil {
    return err
}

for _, role := range rolesPage.Results {
    fmt.Printf("Role: %s\n", *role.GetName())
}

Remove Roles from User

roleIDs := []string{"rol_abc123"}

err := mgmt.Users.RemoveRoles(ctx, userID, roleIDs)
if err != nil {
    return err
}

Working with User Permissions

Assign Permissions to User

permissions := []management.Permission{
    {
        ResourceServerIdentifier: management.String("https://api.example.com"),
        PermissionName:          management.String("read:data"),
    },
    {
        ResourceServerIdentifier: management.String("https://api.example.com"),
        PermissionName:          management.String("write:data"),
    },
}

err := mgmt.Users.AssignPermissions(ctx, userID, permissions)

List User Permissions

permissionsPage, err := mgmt.Users.Permissions(ctx, userID, nil)
if err != nil {
    return err
}

for _, perm := range permissionsPage.Results {
    fmt.Printf("Permission: %s on %s\n",
        *perm.GetPermissionName(),
        *perm.GetResourceServerIdentifier(),
    )
}

Remove Permissions from User

permissions := []management.Permission{
    {
        ResourceServerIdentifier: management.String("https://api.example.com"),
        PermissionName:          management.String("delete:data"),
    },
}

err := mgmt.Users.RemovePermissions(ctx, userID, permissions)

Complete Example

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() {
    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 user
    createUserRequest := &management.CreateUserRequestContent{
        Email:      "newuser@example.com",
        Connection: "Username-Password-Authentication",
        Password:   management.String("TempPassword123!"),
        UserMetadata: map[string]interface{}{
            "preference": "email",
            "plan":       "premium",
        },
        AppMetadata: map[string]interface{}{
            "role":  "user",
            "scope": "read:profile",
        },
    }

    user, err := mgmt.Users.Create(ctx, createUserRequest)
    if err != nil {
        log.Fatalf("Error creating user: %v", err)
    }

    fmt.Printf("Created user: %s (ID: %s)\n",
        *user.GetEmail(),
        *user.GetUserID(),
    )

    // Search for users by email domain
    searchRequest := &management.ListUsersRequestParameters{
        Search:  management.String("email:\"*@example.com\""),
        Sort:    management.String("created_at:1"),
        PerPage: management.Int(25),
    }

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

    fmt.Println("\nUsers with @example.com domain:")
    for _, u := range usersPage.Results {
        fmt.Printf("- %s (Created: %s)\n",
            *u.GetEmail(),
            *u.GetCreatedAt(),
        )
    }

    // Update user metadata
    updateUserRequest := &management.UpdateUserRequestContent{
        UserMetadata: map[string]interface{}{
            "preference":   "sms",
            "plan":         "premium",
            "last_updated": "2024-01-01",
        },
    }

    updatedUser, err := mgmt.Users.Update(
        ctx,
        *user.GetUserID(),
        updateUserRequest,
    )
    if err != nil {
        log.Fatalf("Error updating user: %v", err)
    }

    fmt.Printf("\nUpdated user metadata: %v\n",
        updatedUser.UserMetadata,
    )
}

Next Steps

Client Management

Learn how to manage applications

Connection Management

Learn how to manage connections

Request Options

Customize user operations with request options

Get Started

Core Concepts

Guides

Advanced

Migration

Prerequisites

Creating Users

Reading Users

Get a Single User

List All Users

Updating Users

Searching Users

Search by Email

Search with Multiple Criteria

Sorting Results

Deleting Users

Working with User Roles

Assign Roles to User

List User Roles

Remove Roles from User

Working with User Permissions

Assign Permissions to User

List User Permissions

Remove Permissions from User

Complete Example

Next Steps

Client Management

Connection Management

Request Options

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Migration

Documentation Index

​Prerequisites

​Creating Users

​Reading Users

​Get a Single User

​List All Users

​Updating Users

​Searching Users

​Search by Email

​Search with Multiple Criteria

​Sorting Results

​Pagination

​Deleting Users

​Working with User Roles

​Assign Roles to User

​List User Roles

​Remove Roles from User

​Working with User Permissions

​Assign Permissions to User

​List User Permissions

​Remove Permissions from User

​Complete Example

​Next Steps

Client Management

Connection Management

Request Options

Build docs developers (and LLMs) love

Prerequisites

Creating Users

Reading Users

Get a Single User

List All Users

Updating Users

Searching Users

Search by Email

Search with Multiple Criteria

Sorting Results

Pagination

Deleting Users

Working with User Roles

Assign Roles to User

List User Roles

Remove Roles from User

Working with User Permissions

Assign Permissions to User

List User Permissions

Remove Permissions from User

Complete Example

Next Steps