How to Write Your First Action Module

Get Started

Use the quickstart to write an Action Module and use it from an Action to send logs to an external service.

Create an Action Module

To use an Action Module from a specific Action, you first need to create the Action Module and then add/use it in an Action.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Navigate to Auth0 Dashboard > Actions > Library then select Modules.
Select Create Module.
Enter a Name.
Select Create.

Get a Management API Access Token with the create:actions scope.
Call Create an Actions Module:

curl -L 'https://{yourDomain}/api/v2/actions/modules' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "name": "logger",
    "code": "module.exports = {};",
    "api_version": "1",
    "publish": false
  }'

Auth0 returns the new Action Module, including its id, which you use to reference the module in later steps.

Actions Modules are not natively exposed by the auth0-cli command set, so use auth0 api to call the Management API directly. Some calls require additional scopes — run auth0 login --scopes create:actions,read:actions,update:actions first if needed.

Call Create an Actions Module with auth0 api:

auth0 api post actions/modules --data '{
  "name": "logger",
  "code": "module.exports = {};",
  "api_version": "1",
  "publish": false
}'

Auth0 returns the new Action Module, including its id, which you use to reference the module in later steps.

Read the auth0_action_module resource documentation to learn more.

Add the following resource to a .tf file, referencing the module’s code from a file:

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name = "logger"
  code = file("${path.module}/action-modules/logger/code.js")
}

Create the module’s code file at action-modules/logger/code.js:

action-modules/logger/code.js

module.exports = {};

Run terraform apply.

You will expand the code file and this resource with secrets in the following steps.

YAML
Directory (JSON)

Create the module’s code file at action-modules/logger/code.js:

action-modules/logger/code.js

module.exports = {};

Add an actionModules entry to tenant.yaml:

tenant.yaml

actionModules:
  - name: logger
    code: ./action-modules/logger/code.js

Deploy the configuration:

a0deploy import -c=config.json --input_file=tenant.yaml

Create the module’s configuration file at action-modules/logger.json:

action-modules/logger.json

{
  "name": "logger",
  "code": "./action-modules/logger/code.js"
}

Create the module’s code file at action-modules/logger/code.js:

action-modules/logger/code.js

module.exports = {};

Deploy the configuration:

a0deploy import -c=config.json --input_file=local.

Add a Secret

Each Action Module can contain secret key/values pairs. Use these to hold sensitive information, such as API Keys, certificates, and values that may change across environments.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Next, store the external service URL as a Secret.

Select the icon from the code editor’s left sidebar.
Select Add Secret.
Enter the Name as SERVICE_URL.
Enter the external service URL at the Value field.
Select Create.

Auth0 adds the Secret to the Action Module Secret list.

Next, store the external service URL as a Secret. Call Update an Actions Module with the update:actions scope:

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "secrets": [
      { "name": "SERVICE_URL", "value": "https://example.com/logs" }
    ]
  }'

Each PATCH call replaces the entire secrets array on the module’s draft, so include every Secret the module needs, not just the one you are adding.

Next, store the external service URL as a Secret. Call Update an Actions Module with auth0 api:

auth0 api patch actions/modules/{moduleId} --data '{
  "secrets": [
    { "name": "SERVICE_URL", "value": "https://example.com/logs" }
  ]
}'

Each call replaces the entire secrets array on the module’s draft, so include every Secret the module needs, not just the one you are adding.

Next, store the external service URL as a Secret using a secrets block:

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name = "logger"
  code = file("${path.module}/action-modules/logger/code.js")

  secrets {
    name  = "SERVICE_URL"
    value = "https://example.com/logs"
  }
}

We do not support partial management of secrets. Each terraform apply sends the complete list of secrets defined on the resource.

Next, store the external service URL as a Secret.

YAML
Directory (JSON)

Add a secrets array to the module’s entry in tenant.yaml:

tenant.yaml

actionModules:
  - name: logger
    secrets:
      - name: SERVICE_URL
        value: ##SERVICE_URL##
    code: ./action-modules/logger/code.js

Add a secrets array to action-modules/logger.json:

action-modules/logger.json

{
  "name": "logger",
  "secrets": [
    { "name": "SERVICE_URL", "value": "##SERVICE_URL##" }
  ],
  "code": "./action-modules/logger/code.js"
}

The ##SERVICE_URL## placeholder is resolved through keyword replacement at deploy time, so the actual value never lives in your configuration file.

Extra Step: Repeat the steps to store an API_KEY as a Secret that you will send in the headers to the external service in each request.

Once you create a Secret, Auth0 never reveals its value. Auth0 encrypts all Secrets and stores them securely.

Each Action Module Secret is independent from other Actions Modules and Actions Secrets.

Use Secrets at the Action Module by typing actions.secrets.[secret_key].

Add Custom Logic

Now, add the following code to your Action Module.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Add the following code to your Action Module:

module.exports = {
  sendLog: async (code, message) => {
    try {
      await fetch(actions.secrets.SERVICE_URL, {
        method: 'POST',
        headers: {
          'X-API-Key': actions.secrets.API_KEY,
        },
        body: JSON.stringify({
          code,
          message
        }),
      });

      console.log({
        code,
        message
      });
    } catch (err) {
      throw new Error('External service failure');
    }

    return;
  }
};

Call Update an Actions Module with the following request:

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d @code-update.json

Where code-update.json contains the module’s code as a JSON-escaped string:

code-update.json

{
  "code": "module.exports = {\n  sendLog: async (code, message) => {\n    try {\n      await fetch(actions.secrets.SERVICE_URL, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': actions.secrets.API_KEY,\n        },\n        body: JSON.stringify({ code, message }),\n      });\n\n      console.log({ code, message });\n    } catch (err) {\n      throw new Error('External service failure');\n    }\n\n    return;\n  }\n};"
}

Save the module’s code to code-update.json:

code-update.json

{
  "code": "module.exports = {\n  sendLog: async (code, message) => {\n    try {\n      await fetch(actions.secrets.SERVICE_URL, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': actions.secrets.API_KEY,\n        },\n        body: JSON.stringify({ code, message }),\n      });\n\n      console.log({ code, message });\n    } catch (err) {\n      throw new Error('External service failure');\n    }\n\n    return;\n  }\n};"
}

Then pipe it into Update an Actions Module via auth0 api:

cat code-update.json | auth0 api patch actions/modules/{moduleId}

Update the module’s code file at action-modules/logger/code.js:

action-modules/logger/code.js

module.exports = {
  sendLog: async (code, message) => {
    try {
      await fetch(actions.secrets.SERVICE_URL, {
        method: 'POST',
        headers: {
          'X-API-Key': actions.secrets.API_KEY,
        },
        body: JSON.stringify({
          code,
          message
        }),
      });

      console.log({
        code,
        message
      });
    } catch (err) {
      throw new Error('External service failure');
    }

    return;
  }
};

The auth0_action_module resource’s code attribute already references this file, so run terraform apply to apply the change.

Update action-modules/logger/code.js with the module’s logic:

action-modules/logger/code.js

module.exports = {
  sendLog: async (code, message) => {
    try {
      await fetch(actions.secrets.SERVICE_URL, {
        method: 'POST',
        headers: {
          'X-API-Key': actions.secrets.API_KEY,
        },
        body: JSON.stringify({
          code,
          message
        }),
      });

      console.log({
        code,
        message
      });
    } catch (err) {
      throw new Error('External service failure');
    }

    return;
  }
};

Be aware of:

Save the Draft

You can save a draft of your Action Module.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Select Save Draft.

There is no separate “save” call. Every Update an Actions Module request in the previous steps already persisted your changes to the module’s draft. You can confirm this with Get an Actions Module:

curl -L 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}'

The response’s all_changes_published field is false, confirming the draft has unpublished changes.

There is no separate “save” call. Every auth0 api patch actions/modules/{moduleId} request in the previous steps already persisted your changes to the module’s draft. You can confirm this with Get an Actions Module:

auth0 api get actions/modules/{moduleId}

The response’s all_changes_published field is false, confirming the draft has unpublished changes.

There is no separate “save” step. The terraform apply you ran in the previous steps already updated the module’s draft. The draft has no effect on Actions already using a published version of the module.

Set all_changes_published to false on the module’s entry.

There is no separate “save” step.

YAML
Directory (JSON)

Update tenant.yaml:

tenant.yaml

actionModules:
  - name: logger
    all_changes_published: false
    secrets:
      - name: SERVICE_URL
        value: ##SERVICE_URL##
    code: ./action-modules/logger/code.js

Redeploy the configuration to publish the change:

a0deploy import -c=config.json --input_file=tenant.yaml

Update action-modules/logger.json:

action-modules/logger.json

{
  "all_changes_published": false,
  "name": "logger",
  "secrets": [
    { "name": "SERVICE_URL", "value": "##SERVICE_URL##" }
  ],
  "code": "./action-modules/logger/code.js"
}

Redeploy the configuration to publish the change:

a0deploy import -c=config.json --input_file=local.

This saves your Action Module without publishing a new version, so it does not affect Actions using it.

Publish the Action Module

Once you are satisfied with the Action Module code, it’s time to Publish it.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Select Publish.

Publishing an Action Module takes a snapshot of it at that time and records it as an Action Module Version.

Select View Version History.

Auth0 displays the list of Action Module Versions including the draft.

Call Create an Actions Module Version, which takes a snapshot of the current draft and publishes it:

curl -L -X POST 'https://{yourDomain}/api/v2/actions/modules/{moduleId}/versions' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}'

Auth0 returns the new Action Module Version, including its id and version_number. You’ll reference this id as the module_version_id when adding the module to an Action.

Call Create an Actions Module Version with auth0 api, which takes a snapshot of the current draft and publishes it:

auth0 api post actions/modules/{moduleId}/versions

Auth0 returns the new Action Module Version, including its id and version_number. You’ll reference this id as the module_version_id when adding the module to an Action.

Set publish to true on the resource, then run terraform apply:

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name    = "logger"
  code    = file("${path.module}/action-modules/logger/code.js")
  publish = true

  secrets {
    name  = "SERVICE_URL"
    value = "https://example.com/logs"
  }
}

Publishing creates a new Action Module Version from the current draft. Terraform exposes the published version’s ID as the version_id computed attribute, which you reference from auth0_action resources as module_version_id.

Set all_changes_published to true on the module’s entry.

YAML
Directory (JSON)

Update tenant.yaml:

tenant.yaml

actionModules:
  - name: logger
    all_changes_published: true
    secrets:
      - name: SERVICE_URL
        value: ##SERVICE_URL##
    code: ./action-modules/logger/code.js

Redeploy the configuration to publish the change:

a0deploy import -c=config.json --input_file=tenant.yaml

Update action-modules/logger.json:

action-modules/logger.json

{
  "all_changes_published": true,
  "name": "logger",
  "secrets": [
    { "name": "SERVICE_URL", "value": "##SERVICE_URL##" }
  ],
  "code": "./action-modules/logger/code.js"
}

Redeploy the configuration to publish the change:

a0deploy import -c=config.json --input_file=local.

This publishes a new Action Module Version from the current draft after applying your changes.

You are now able to start using the Action Module in an Action.

Each Action must explicitly reference the Action Module Version, preventing automatic upgrades that could introduce unexpected errors.

Add the Action Module in an Action

Next, add the Action Module in an Action.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Navigate to Auth0 Dashboard > Actions > Library then select a specific Action.
Once at the Action Editor, select the icon from the left sidebar.
Select Add Module.
Select a Module Name and Version.
Select Add.

Call Update an Action with the module’s module_id and module_version_id from the previous step:

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/actions/{actionId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "modules": [
      {
        "module_id": "{moduleId}",
        "module_version_id": "{moduleVersionId}"
      }
    ]
  }'

auth0 actions update has no flag for Action Modules, so call Update an Action directly with auth0 api, using the module’s module_id and module_version_id from the previous step:

auth0 api patch actions/actions/{actionId} --data '{
  "modules": [
    {
      "module_id": "{moduleId}",
      "module_version_id": "{moduleVersionId}"
    }
  ]
}'

Add a modules block to the auth0_action resource, referencing the module and its published version. Keep the code attribute pointing at the Action’s own code file:

actions/my-action.tf

resource "auth0_action" "my_action" {
  name = "my-action"
  code = file("${path.module}/actions/my-action/code.js")

  modules {
    module_id         = auth0_action_module.logger.id
    module_version_id = auth0_action_module.logger.version_id
  }

  supported_triggers {
    id      = "post-login"
    version = "v3"
  }
}

Add a modules array to the Action’s configuration, referencing the module by name and version number.

YAML
Directory (JSON)

Add the modules array to the Action’s entry in tenant.yaml:

tenant.yaml

actions:
  - name: my-action
    code: ./actions/my-action/code.js
    supported_triggers:
      - id: post-login
        version: v3
    modules:
      - module_name: logger
        module_version_number: 1

Add the modules array to the Action’s configuration file (for example, actions/my-action.json):

actions/my-action.json

{
  "modules": [
    { "module_name": "logger", "module_version_number": 1 }
  ],
  "name": "my-action",
  "code": "./actions/my-action/code.js",
  "supported_triggers": [
    { "id": "post-login", "version": "v3" }
  ]
}

The Deploy CLI resolves module_name and module_version_number to the module’s real module_id and module_version_id at deploy time.

Use the Action Module in the Action

Now, let’s use the Action Module in the Action.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Add the require statement.

const logger = require('actions:logger');

The require statement references the Action Module with the format actions:[module-name].

Add the call to logger.sendLog in the Action function, where you want to send logs.

await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');

Select Deploy the Action.

Call Update an Action to add the require statement and the call to logger.sendLog to the Action’s code:

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/actions/{actionId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d @code-update.json

Where code-update.json contains:

code-update.json

{
  "code": "const logger = require('actions:logger');\n\nexports.onExecutePostLogin = async (event, api) => {\n  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');\n};"
}

Call Deploy an Action:

curl -L -X POST 'https://{yourDomain}/api/v2/actions/actions/{actionId}/deploy' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}'

Update the Action’s code file at actions/my-action/code.js with the require statement and the call to logger.sendLog:

actions/my-action/code.js

const logger = require('actions:logger');

exports.onExecutePostLogin = async (event, api) => {
  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');
};

Update the Action with auth0 actions update and deploy it with auth0 actions deploy:

auth0 actions update {actionId} --code "$(cat actions/my-action/code.js)"
auth0 actions deploy {actionId}

Update the Action’s code file at actions/my-action/code.js with the require statement and the call to logger.sendLog:

actions/my-action/code.js

const logger = require('actions:logger');

exports.onExecutePostLogin = async (event, api) => {
  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');
};

Set deploy to true on the auth0_action resource, then run terraform apply:

actions/my-action.tf

resource "auth0_action" "my_action" {
  name    = "my-action"
  deploy  = true
  code    = file("${path.module}/actions/my-action/code.js")

  modules {
    module_id         = auth0_action_module.logger.id
    module_version_id = auth0_action_module.logger.version_id
  }

  supported_triggers {
    id      = "post-login"
    version = "v3"
  }
}

Setting deploy = true immediately creates a new, deployed version of the Action.

Add the require statement and the call to logger.sendLog to actions/my-action/code.js:

actions/my-action/code.js

const logger = require('actions:logger');

exports.onExecutePostLogin = async (event, api) => {
  await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');
};

Redeploy the configuration:

a0deploy import -c=config.json --input_file=local.

Remember to bind the Action to a Trigger.

CheckpointYou should now have a fully functional Action Module being used by an Action.

Advanced Usage

NPM Dependencies

Each Action Module can add/use NPM Dependencies.

Dashboard
Management API
Auth0 CLI
Terraform
Auth0 Deploy CLI

Select the icon from the code editor’s left sidebar.
Select Add Dependency.
Enter the Name of the NPM package.
Enter the Version of the NPM package.
Select Create.

Auth0 adds the Dependency to the Action Module Dependency list.

Call Update an Actions Module with a dependencies array:

curl -L -X PATCH 'https://{yourDomain}/api/v2/actions/modules/{moduleId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {yourMgmtApiAccessToken}' \
  -d '{
    "dependencies": [
      { "name": "lodash", "version": "4.17.21" }
    ]
  }'

As with secrets, each PATCH call replaces the entire dependencies array, so include every dependency the module needs.

Call Update an Actions Module with auth0 api, using a dependencies array:

auth0 api patch actions/modules/{moduleId} --data '{
  "dependencies": [
    { "name": "lodash", "version": "4.17.21" }
  ]
}'

As with secrets, each call replaces the entire dependencies array, so include every dependency the module needs.

Add a dependencies block to the auth0_action_module resource, then run terraform apply:

action-modules/logger.tf

resource "auth0_action_module" "logger" {
  name = "logger"
  code = file("${path.module}/action-modules/logger/code.js")

  dependencies {
    name    = "lodash"
    version = "4.17.21"
  }
}

Add a dependencies array to the module’s configuration.

YAML
Directory (JSON)

Add the dependencies array to the module’s entry in tenant.yaml:

tenant.yaml

actionModules:
  - name: logger
    dependencies:
      - name: lodash
        version: 4.17.21
    code: ./action-modules/logger/code.js

Add the dependencies array to action-modules/logger.json:

action-modules/logger.json

{
  "dependencies": [
    { "name": "lodash", "version": "4.17.21" }
  ],
  "name": "logger",
  "code": "./action-modules/logger/code.js"
}

Use the listed Dependencies at the Action Module by requiring them through require('[package-name]').

When you save this Action, Auth0 resolves the latest version of your dependency and replaces it with a specific version number to keep future updates to the package from breaking your Action.You can provide a specific version instead of latest.

Concepts

How To

Reference

Use Cases

How to Write Your First Action Module

Get Started

Create an Action Module

Add a Secret

Add Custom Logic

Save the Draft

Publish the Action Module

Add the Action Module in an Action

Use the Action Module in the Action

Advanced Usage

​Get Started

Create an Action Module

Add a Secret

Add Custom Logic

Save the Draft

Publish the Action Module

Add the Action Module in an Action

Use the Action Module in the Action

​Advanced Usage

Get Started

Advanced Usage