How to Implement Passwordless Authentication in Logto: Complete Developer Guide

Logto implements passwordless authentication through a verification-code flow using SMS or email connectors, eliminating the need for passwords while maintaining security via the /api/experience/verification/password endpoint.

To implement passwordless authentication in Logto, you configure connectors that dispatch verification codes via email or SMS, then leverage the Logto SDK to handle the sign-in flow. The logto-io/logto repository provides the core infrastructure, connector implementations, and admin console configuration required to enable passwordless login for your tenants.

Understanding Logto's Passwordless Architecture

Logto's passwordless system relies on a verification-code flow that authenticates users through possession of their email address or phone number rather than memorized credentials.

The Verification Code Flow

When a user initiates passwordless sign-in, Logto generates a one-time code and dispatches it through a configured connector. The core verification logic resides in packages/core/src/routes/experience/verification-routes/password-verification.ts, which exposes the /api/experience/verification/password endpoint. This route validates the submitted code against the stored verification record and, upon success, creates an authenticated session without requiring a password.

Core Data Structures

The connector interface defines the data structure for passwordless messages in packages/toolkit/connector-kit/src/types/passwordless.ts. The SendMessageData interface carries the verification payload:

interface SendMessageData {
  to: string;                    // Email or phone number
  type: TemplateType;            // e.g., TemplateType.SignIn
  payload: { code: string };     // The generated verification code
  ip?: string;                   // Client IP for rate-limiting
}

The TemplateType enum distinguishes between sign-in, register, and forgot-password scenarios, while SendMessagePayload contains the dynamic content injected into message templates.

Configuring Passwordless Connectors

Logto ships with official connectors for HTTP-based email and SMS providers. These implement the sendMessage function that consumes SendMessageData and forwards it to external services.

Email Connector Setup

The connector-http-email package located at packages/connectors/connector-http-email/src/index.ts implements the email delivery logic. When configured, it receives the SendMessageData object and POSTs the verification details to your specified email service endpoint.

To configure the connector, you specify the endpoint URL, authorization headers, and template mappings in the Logto admin console. The template uses the {{code}} placeholder, which the connector populates from payload.code before transmission.

SMS Connector Setup

Similarly, packages/connectors/connector-http-sms/src/index.ts handles SMS delivery. The connector transforms the SendMessageData into the payload format required by your SMS gateway, ensuring the verification code reaches the user's device via text message.

Both connectors support the ip field for fraud detection, allowing you to implement rate-limiting based on client IP addresses at the connector level.

Implementing the Authentication Flow

Client applications use the @logto/js SDK to initiate and complete passwordless authentication. The SDK abstracts the API calls to Logto's internal routes while handling token retrieval.

Starting the Passwordless Sign-In

Import the Logto client and trigger the passwordless flow by calling the email or SMS sign-in method:

import { createLogtoClient } from '@logto/js';

const logto = createLogtoClient({
  endpoint: 'https://your-logto-instance.com',
  appId: 'your-app-id',
});

// Initiate passwordless flow - Logto sends verification code via connector
await logto.signInByEmail('user@example.com');

Behind the scenes, Logto generates a verification code, constructs the SendMessageData object, and invokes the configured connector's sendMessage function. The user receives the code via their chosen channel.

Verifying the Code and Creating Sessions

Once the user provides the verification code, the SDK submits it to the verification endpoint:

// Submit the code received via email or SMS
await logto.verifyPasswordlessCode({
  identifier: 'user@example.com',
  verificationCode: '123456',  // Code entered by user
});

// Retrieve tokens after successful verification
const { accessToken, idToken } = logto.getTokens();

The verifyPasswordlessCode method calls the verification route implemented in packages/core/src/routes/experience/verification-routes/password-verification.ts. Upon validation, Logto creates a session and returns authentication tokens identical to traditional password-based flows.

Enabling Passwordless in the Admin Console

Before the API flows become functional, you must enable passwordless authentication at the tenant level. In the Logto admin console, navigate to Sign-in Experience → Connectors and toggle the Passwordless option. The UI renders this control using the SVG assets located at packages/console/src/assets/icons/passwordless.svg and passwordless-dark.svg for light and dark themes respectively.

After enabling the feature, configure your connectors with the appropriate API endpoints and template mappings. The integration test suite at packages/integration-tests/src/tests/console/connectors/passwordless-connectors.test.ts provides end-to-end validation examples for verifying your configuration.

Summary

• Logto's passwordless flow uses verification codes delivered via email or SMS connectors rather than passwords, with core logic in packages/core/src/routes/experience/verification-routes/password-verification.ts.
• Data structures defined in packages/toolkit/connector-kit/src/types/passwordless.ts standardize message payloads through SendMessageData, TemplateType, and SendMessagePayload.
• Connector implementations in packages/connectors/connector-http-email/src/index.ts and connector-http-sms handle the actual message dispatch to external providers.
• Client integration uses the @logto/js SDK methods signInByEmail and verifyPasswordlessCode to orchestrate the flow and retrieve tokens.
• Admin configuration requires enabling the passwordless toggle in the sign-in experience settings and configuring connector endpoints with proper template variables.

Frequently Asked Questions

What data structure does Logto use for passwordless messages?

Logto uses the SendMessageData interface defined in packages/toolkit/connector-kit/src/types/passwordless.ts. This structure contains the recipient address (to), template type (type), dynamic payload including the verification code (payload), and optional client IP (ip) for security logging.

Where is the passwordless verification endpoint implemented?

The verification endpoint is implemented in packages/core/src/routes/experience/verification-routes/password-verification.ts. This route handles POST requests to /api/experience/verification/password, validates the submitted code against stored records, and creates an authenticated session upon successful verification.

How do I configure the email template for verification codes?

Configure templates in the Logto admin console when setting up the connector-http-email connector. The template should include the {{code}} placeholder, which the connector automatically replaces with the generated verification code from the payload.code field before sending the message to your email service API.

Can I use custom SMS providers for passwordless authentication?

Yes. While Logto provides connector-http-sms for generic HTTP-based SMS gateways, you can implement custom connectors by adhering to the SendMessageData interface defined in the connector kit. Your custom connector must implement the sendMessage function to transform Logto's standardized payload into your specific SMS provider's API format.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}