Skip to main content
Rules are JavaScript functions that execute when a user authenticates to your application. They allow you to customize and extend Auth0’s capabilities. Use this resource to create, retrieve, update, and delete rules.
Rules are being deprecated in favor of Actions. While existing rules will continue to function, we recommend migrating to Actions for new implementations.

​
Methods

​
List Rules

Retrieve a filtered list of rules. 
func (c *Client) List(
    ctx context.Context,
    request *management.ListRulesRequestParameters,
    opts ...option.RequestOption,
) (*core.Page[*int, *management.Rule, *management.ListRulesOffsetPaginatedResponseContent], error)
​
request
*management.ListRulesRequestParameters
Query parameters for filtering and pagination
​
Rule
*management.Rule

​
Example

ctx := context.Background()

listRequest := &management.ListRulesRequestParameters{
    Enabled: management.Bool(true),
    PerPage: management.Int(25),
}

rulesPage, err := mgmt.Rules.List(ctx, listRequest)
if err != nil {
    log.Fatalf("Error listing rules: %v", err)
}

// Iterate through rules
iterator := rulesPage.Iterator()
for iterator.Next(ctx) {
    rule := iterator.Current()
    fmt.Printf("Rule: %s (Order: %.0f)\n", 
        rule.GetName(), 
        rule.GetOrder(),
    )
}

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

​
Create Rule

Create a new rule. 
func (c *Client) Create(
    ctx context.Context,
    request *management.CreateRuleRequestContent,
    opts ...option.RequestOption,
) (*management.CreateRuleResponseContent, error)
​
request
*management.CreateRuleRequestContent
required

​
Example

ruleScript := `function (user, context, callback) {
  // Add custom claims to the access token
  context.accessToken['https://myapp.com/user_metadata'] = user.user_metadata;
  callback(null, user, context);
}`

createRequest := &management.CreateRuleRequestContent{
    Name:    "Add User Metadata to Token",
    Script:  ruleScript,
    Enabled: management.Bool(true),
    Order:   management.Float64(1),
}

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

fmt.Printf("Created rule: %s (ID: %s)\n", rule.GetName(), rule.GetID())
Changing a rule’s stage from the default login_success can change the function signature to have the user parameter omitted.

​
Get Rule

Retrieve rule details by ID. 
func (c *Client) Get(
    ctx context.Context,
    id string,
    request *management.GetRuleRequestParameters,
    opts ...option.RequestOption,
) (*management.GetRuleResponseContent, error)
​
id
string
required
ID of the rule to retrieve

​
Example

rule, err := mgmt.Rules.Get(ctx, "rul_abc123", 
    &management.GetRuleRequestParameters{})
if err != nil {
    log.Fatalf("Error retrieving rule: %v", err)
}

fmt.Printf("Rule: %s\n", rule.GetName())
fmt.Printf("Enabled: %t\n", rule.GetEnabled())
fmt.Printf("Order: %.0f\n", rule.GetOrder())

​
Update Rule

Update an existing rule. 
func (c *Client) Update(
    ctx context.Context,
    id string,
    request *management.UpdateRuleRequestContent,
    opts ...option.RequestOption,
) (*management.UpdateRuleResponseContent, error)
​
id
string
required
ID of the rule to update
​
request
*management.UpdateRuleRequestContent
required

​
Example

updateRequest := &management.UpdateRuleRequestContent{
    Enabled: management.Bool(false), // Disable the rule
    Order:   management.Float64(5),   // Change execution order
}

updatedRule, err := mgmt.Rules.Update(ctx, "rul_abc123", updateRequest)
if err != nil {
    log.Fatalf("Error updating rule: %v", err)
}

fmt.Printf("Updated rule: %s (Enabled: %t)\n", 
    updatedRule.GetName(), 
    updatedRule.GetEnabled())

​
Delete Rule

Delete a rule. 
func (c *Client) Delete(
    ctx context.Context,
    id string,
    opts ...option.RequestOption,
) error
​
id
string
required
ID of the rule to delete

​
Example

err := mgmt.Rules.Delete(ctx, "rul_abc123")
if err != nil {
    log.Fatalf("Error deleting rule: %v", err)
}

fmt.Println("Rule deleted successfully")

​
Rule Stages

Rules can execute at different stages:
  • login_success (default): Executes after successful authentication
  • login_failure: Executes after failed authentication
  • pre_authorize: Executes before token issuance

​
Execution Order

Rules execute in the order specified by the Order field. Lower values execute first: 
// Rule with Order = 1 executes first
// Rule with Order = 2 executes second
// Rule with Order = 3 executes third

​
Best Practices

Migration to Actions

Consider migrating to Actions for new implementations. Actions provide better performance, debugging, and integration capabilities.

Rule Organization

Use the Order field to control rule execution sequence. Organize rules logically based on their dependencies.

Error Handling

Always handle errors in rule scripts and use proper callback patterns to avoid breaking the authentication flow.

Testing

Test rules thoroughly in a development environment before enabling them in production. Disabled rules don’t execute.

Build docs developers (and LLMs) love

Get started for freeTalk to us