Write Your First Action Module - Auth0 Docs

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

1. Navigate to Auth0 Dashboard > Actions > Library then select Modules.

2. Select Create Module.

3. Enter a Name.

4. Select Create.

5. Get a Management API Access Token with the create:actions scope.

6. 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.

Call Create an Actions Module with auth0 api:

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

1. 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")
}

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

action-modules/logger/code.js

module.exports = {};

3. Run terraform apply.

Add a Secret

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

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

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" }\
    ]
  }'

Next, store the external service URL as a Secret.

Add an actionModules entry to tenant.yaml:

tenant.yaml

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

Add Custom Logic

Now, 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};"
}

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

action-modules/logger/code.js

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

return; } };

### Save the Draft

You can save a draft of your Action Module.

1. Select **Save Draft**.

There is no separate “save” call. Every [Update an Actions Module](/content/docs/api/management/v2/actions/patch-action-module/index.html) request in the previous steps has already persisted your changes to the module’s draft. You can confirm this with [Get an Actions Module](/content/docs/api/management/v2/actions/get-action-module/index.html):

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

### Publish the Action Module

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

1. Select **Publish**.

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

Call [Create an Actions Module Version](/content/docs/api/management/v2/actions/post-action-module-version/index.html):

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

### Add the Action Module in an Action

Next, add the Action Module in an Action.

1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library) then select a specific **Action**.

2. Call [Update an Action](/content/docs/api/management/v2/actions/patch-action/index.html) 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}"
}
] }'

### Use the Action Module in the Action

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

1. Add the **require** statement.

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

2. 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');

3. Select **Deploy** the Action.

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

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.