Registry / auth-security / better-auth-telegram

better-auth-telegram

library1.5.0jsnpmunverified

better-auth-telegram is a plugin for the Better Auth framework, providing comprehensive Telegram authentication capabilities. It supports various Telegram login methods including the traditional Login Widget, Mini Apps, and the more modern OpenID Connect (OIDC) flow, leveraging OAuth 2.0 Authorization Code flow with PKCE. The library handles HMAC-SHA-256 verification and is built on the Web Crypto API, ensuring compatibility across diverse JavaScript runtimes like Node.js (>=22.0.0), Bun, and Cloudflare Workers, without relying on Node.js-specific `node:crypto` modules. The current stable version is 1.5.0, with an active release cadence addressing features, fixes, and compatibility. It integrates seamlessly with Better Auth's client and server-side components, and offers explicit guidance for database schema updates, making it a robust solution for integrating Telegram login into applications.

auth-security web-framework

npm install better-auth-telegram

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-TELEGR

better-auth-telegram

auth-securityjavascriptv1.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { telegram } from 'better-auth-telegram';

✗ const { telegram } = require('better-auth-telegram');

This is the server-side plugin export. ESM-only for Node.js >=22.0.0 environments, as specified in `engines`.

telegramClient

✓ import { telegramClient } from 'better-auth-telegram/client';

✗ import { telegramClient } from 'better-auth-telegram';

This is the client-side plugin export, imported from a subpath. Ensure you target the `/client` entry point for browser-specific code.

✓ import type { TelegramConfig } from 'better-auth-telegram';

✗ import { TelegramConfig } from 'better-auth-telegram';

When importing types, use `import type` for clarity and to ensure they are stripped during compilation, preventing accidental runtime imports.

Initializes the server-side Telegram authentication plugin for Better Auth using a bot token and username.

import { betterAuth } from "better-auth"; import { telegram } from "better-auth-telegram"; // Ensure TELEGRAM_BOT_TOKEN is set in your environment variables. // For local development, consider using ngrok for HTTPS as Telegram requires it. export const auth = betterAuth({ plugins: [ telegram({ botToken: process.env.TELEGRAM_BOT_TOKEN ?? '', // Use environment variable botUsername: "your_bot_username", // Replace with your bot's username (without @) // Optional: Disable Login Widget if only using OIDC and to avoid schema clutter // loginWidget: false, // Optional: Enable OIDC and provide client secret (from BotFather > Web Login) // oidc: { enabled: true, clientSecret: process.env.TELEGRAM_OIDC_CLIENT_SECRET ?? '' }, }), ], }); console.log("Telegram plugin initialized for Better Auth. Make sure your environment variables are configured."); // In a real application, you would now expose 'auth' via an API handler or similar.

Debug

Known issues

breakingWhen upgrading `better-auth` to `1.5.0` or higher, `better-auth-telegram` versions prior to `1.1.0` experienced type errors due to changes in Better Auth's error code structure (`$ERROR_CODES` changed from `Record<string, string>` to `Record<string, RawError>`).

fix

Upgrade `better-auth-telegram` to `1.1.0` or higher to ensure compatibility with `better-auth@^1.5.0`. The plugin now uses `defineErrorCodes()` for error code migration.

affects: <1.1.0

gotchaFor OIDC authentication, the `clientSecret` is distinct from the `botToken`. Many users incorrectly use the bot token for the OIDC client secret, leading to `invalid_client` errors. The `clientSecret` must be obtained from BotFather via 'Bot Settings > Web Login'.

fix

Ensure you retrieve the correct 'Client Secret' for Web Login from BotFather, not the main bot token. This fix was explicitly addressed in v1.4.0.

affects: >=1.0.0

gotchaWhen performing client-side operations like `linkTelegram` or `unlinkTelegram`, if you encounter 'Not authenticated' errors, it's likely due to missing credentials in your `fetchOptions`.

fix

Ensure your `createAuthClient` configuration includes `fetchOptions: { credentials: "include" }` to send cookies/credentials with requests.

affects: >=1.0.0

gotchaWhen using OIDC-only setups, by default, the plugin adds database fields for the Login Widget/Mini Apps (`telegramId`, `telegramUsername`, `telegramPhoneNumber` to `User`, and `telegramId`, `telegramUsername` to `Account`). This can clutter your schema if not needed.

fix

Set `loginWidget: false` in the plugin configuration to disable Login Widget endpoints and omit Telegram-specific schema fields for OIDC-only integrations.

affects: >=1.5.0

Errors

Common errors & fixes

Error: invalid_client

Incorrect client secret provided for OIDC. The bot token was used instead of the specific Web Login client secret.

fix

Obtain the correct 'Client Secret' for Web Login from BotFather ('Bot Settings > Web Login') and use it for the `oidc.clientSecret` option.

Not authenticated

Client-side requests (e.g., `linkTelegram`, `unlinkTelegram`) are not sending authentication credentials (cookies) to the server.

fix

Configure your `createAuthClient` with `fetchOptions: { credentials: 'include' }`.

Property '$ERROR_CODES' does not exist on type 'BetterAuthPlugin'.

Type incompatibility between `better-auth-telegram` and `better-auth` due to a change in the `better-auth`'s internal error code structure.

fix

Upgrade `better-auth-telegram` to version `1.1.0` or higher to resolve the type mismatch with `better-auth@^1.5.0`.

Upgrade

Version history

1.5.0latest on npm

Audit

Dependencies

better-authrequiredCore authentication framework that this package extends.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vcode-sh/better-auth-telegram ↗

packagehttps://www.npmjs.com/package/better-auth-telegram ↗

homepagehttps://better-auth.com ↗