Skip to main content
This guide walks you through adding Telegram authentication to a React or Next.js app from scratch. By the end you will have a working sign-in button that verifies users cryptographically on your server — no passwords, no SMS, no OAuth redirects. The whole setup takes about five minutes.
1

Create a Bondify account

Go to https://bondify.dev/sign-up and create a free account. The Starter plan is free forever and includes 1,000 authentications per month — no credit card required.
2

Create a project and copy your credentials

In the Bondify dashboard, click Create project, give it a name, and hit Save. Bondify generates two credentials for you:
  • Project ID — a public identifier in the format proj_xxxxxxxx. Safe to expose in client-side code.
  • Secret key — a server-side secret in the format sk_.... Keep this private; never commit it to git or expose it in the browser.
Copy both values — you will need them in the next step.
Your secret key is shown in full only once at creation time. Store it somewhere safe immediately. If you lose it, regenerate it from the project settings — all existing sessions will remain valid.
3

Install the SDK

Add the Bondify packages to your project. Install the React client package and the server-side verification package separately so you never accidentally bundle your secret key into client code.
npm install @bondify/sdk @bondify/react @bondify/server
4

Set your environment variables

Add the following to your .env.local (Next.js) or .env file. Prefix the project ID with NEXT_PUBLIC_ so it is available in the browser bundle; keep the secret key unprefixed so it stays server-only.
.env.local
NEXT_PUBLIC_BONDIFY_PROJECT_ID=proj_xxxxxxxx
BONDIFY_SECRET_KEY=sk_...
Never expose BONDIFY_SECRET_KEY to the client. In Next.js, any variable without the NEXT_PUBLIC_ prefix is automatically excluded from the browser bundle.
5

Add the sign-in button to your frontend

Wrap your login page in PulseProvider and render a PulseButton. When the user taps the button, Bondify opens Telegram, waits for the user to confirm, and calls your onSuccess handler with the user object and a signed proof token.
app/login/page.tsx
import { PulseProvider, PulseButton } from '@bondify/react';

export default function LoginPage() {
  return (
    <PulseProvider projectId={process.env.NEXT_PUBLIC_BONDIFY_PROJECT_ID!}>
      <PulseButton
        onSuccess={(user) => {
          // user.telegramId  — Telegram numeric user ID
          // user.name        — user's display name
          // user.username    — @username (may be null)
          // user.proof       — signed JWT to verify server-side
          fetch('/api/session', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ proof: user.proof }),
          });
        }}
      />
    </PulseProvider>
  );
}
The proof returned in onSuccess is a JWT signed by Bondify. It proves the user completed the Telegram confirmation step, but you must verify it on your server before trusting it. Never use the raw proof data to create a session client-side.
6

Verify the proof on your server

On your API route, call verifyProof from @bondify/server with the proof and your secret key. If verification succeeds, the function returns the verified user object and you can issue your own session cookie or JWT.
import { verifyProof } from '@bondify/server';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { proof } = await req.json();

  try {
    const user = await verifyProof(
      proof,
      process.env.BONDIFY_SECRET_KEY!
    );
    // user.telegramId, user.name, user.username
    // Issue your own session here (cookie, JWT, etc.)
    return NextResponse.json({ ok: true, telegramId: user.telegramId });
  } catch (err) {
    return NextResponse.json({ error: 'Invalid proof' }, { status: 401 });
  }
}
That’s it — your app now has one-tap Telegram authentication.

​
What’s next?

Explore framework-specific guides, the HTML widget for non-React projects, and the full REST API reference.

React

Deep-dive into PulseProvider, PulseButton props, hooks, and theming.

HTML Widget

Add Bondify to any page with a single <script> tag and a data attribute.

Next.js

Server Actions, middleware auth guards, and App Router patterns.

Node.js

Express and Fastify examples for server-side proof verification.

Flutter

The bondify_flutter package for iOS and Android apps.

API Reference

Full REST API docs — session creation, polling, webhooks, and more.