Logto Connector: Novu Email

A Logto email connector that integrates with Novu to send verification codes during user authentication flows.

Features

• 🔐 Passwordless email authentication via Novu
• 📧 Support for all Logto email flows:
  • User Registration
  • Sign In
  • Password Recovery
  • Continue Flow
  • Generic Verification
• 🎨 Flexible workflow configuration
• ⚡ Built with TypeScript and Zod validation
• 🌍 Multi-language support

Installation

npm install @quickguidehealth/connector-logto-novu

Prerequisites

Before using this connector, you need:

1. A Novu account with an API key
2. Configured Novu workflows for each authentication flow you want to support
3. A running Logto instance

Configuration

Step 1: Create Novu Workflows

In your Novu dashboard, create workflows for each authentication flow. Each workflow should:

• Have an Email step configured
• Accept a code payload variable
• Be published and active

Example workflow configuration:

• Trigger Identifier: user-registration-verification
• Email Template: Include {{code}} where the verification code should appear

Step 2: Configure the Connector in Logto

When setting up the connector in your Logto Admin Console, use the following JSON configuration format:

{
  "secretKey": "your-novu-secret-key",
  "serverUrl": "https://eu.api.novu.co",
  "templates": [
    {
      "usageType": "Register",
      "workflowId": "user-registration-verification",
      "workflowName": "User Registration"
    },
    {
      "usageType": "SignIn",
      "workflowId": "user-signin-verification",
      "workflowName": "User Sign In"
    },
    {
      "usageType": "ForgotPassword",
      "workflowId": "password-recovery-verification",
      "workflowName": "Password Recovery"
    },
    {
      "usageType": "Generic",
      "workflowId": "generic-verification",
      "workflowName": "Generic Verification"
    },
    {
      "usageType": "OrganizationInvitation",
      "workflowId": "org-invitation",
      "workflowName": "Organization Invitation"
    },
    {
      "usageType": "UserPermissionValidation",
      "workflowId": "permission-validation",
      "workflowName": "Permission Validation"
    },
    {
      "usageType": "BindNewIdentifier",
      "workflowId": "bind-identifier",
      "workflowName": "Bind New Identifier"
    },
    {
      "usageType": "MfaVerification",
      "workflowId": "mfa-verification",
      "workflowName": "MFA Verification"
    },
    {
      "usageType": "BindMfa",
      "workflowId": "bind-mfa",
      "workflowName": "Bind MFA"
    }
  ],
  "fromEmail": "[email protected]",
  "fromName": "Your App Name"
}

Configuration Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | secretKey | string | Yes | Your Novu API secret key | | serverUrl | string | No | Novu server URL (default: https://eu.api.novu.co) | | templates | array | Yes | Array of template configurations (at least one required) | | fromEmail | string | No | Override the default from email address | | fromName | string | No | Override the default from name |

Server URL Options

| Region | URL | |--------|-----| | EU (default) | https://eu.api.novu.co | | US | https://api.novu.co | | Self-hosted | https://novu.your-domain.com |

Template Configuration

Each template in the templates array must include:

| Field | Type | Required | Description | |-------|------|----------|-------------| | usageType | enum | Yes | See "Usage Type Guide" below | | workflowId | string | Yes | The Novu workflow identifier to trigger | | workflowName | string | No | Human-readable name for documentation |

Usage Type Guide

• Register: Sent when a new user signs up
• SignIn: Sent when an existing user signs in with passwordless authentication
• ForgotPassword: Sent when a user requests a password reset
• Generic: Sent for generic verification purposes
• OrganizationInvitation: Sent when inviting users to an organization
• UserPermissionValidation: Sent to verify identity for sensitive operations
• BindNewIdentifier: Sent when binding a new email to an account
• MfaVerification: Sent for MFA challenges during login
• BindMfa: Sent when setting up email-based MFA

How It Works

1. When a user triggers an authentication flow in Logto that requires email verification
2. Logto calls this connector's sendMessage method
3. The connector finds the appropriate Novu workflow based on the usage type
4. A Novu workflow is triggered with the verification code
5. Novu delivers the email to the user
6. The user enters the code to complete authentication

Novu Workflow Payload

When the connector triggers a Novu workflow, it sends the following payload:

{
  to: {
    subscriberId: "[email protected]",
    email: "[email protected]"
  },
  payload: {
    code: "123456",
    email: "[email protected]",
    type?: "Register" | "SignIn" | "ForgotPassword" | "Continue" | "Generic"
  },
  overrides?: {
    email: {
      from?: "[email protected]",
      senderName?: "Your App Name"
    }
  }
}

In your Novu email templates, you can access:

• {{code}} - The verification code
• {{email}} - The recipient's email address
• {{type}} - The authentication flow type

Troubleshooting

"Cannot find Novu workflow template for usage type"

Cause: The configuration doesn't include a template for the requested usage type.

Solution: Add a template configuration for the missing usage type in your connector configuration.

"Failed to send email via Novu"

Cause: Novu API request failed.

Possible solutions:

• Verify your Novu secret key is correct
• Check that the workflow IDs exist and are published in Novu
• Ensure your Novu account is active and not rate-limited
• Check Novu's dashboard for error logs

"Verification code is required in payload"

Cause: Logto didn't provide a verification code in the request.

Solution: This is usually a Logto configuration issue. Ensure your authentication flow is properly configured.

Development

Building

npm run build

Development Mode

npm run dev

Clean Build Artifacts

npm run clean

Related Links

• Logto Documentation
• Logto Connector Development Guide
• Novu Documentation
• Novu TypeScript SDK

License

MIT © QuickGuide Health

Support

For issues and questions:

• GitHub Issues: https://github.com/QuickGuideHealth/quickguide-packages/issues
• Logto Discord: https://discord.gg/logto
• Novu Discord: https://discord.gg/novu

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.