Stateless auth without a database round-trip: how Bondify's proof model works

The shape of the problem

Most "login with X" integrations work the same way: your server gets a token, and to find out if it's real, it has to ask the provider. That round-trip is one more network call on your auth hot path, one more thing that can time out, and one more dependency between your uptime and theirs.

Bondify doesn't do that. Verification is local — a single HMAC check against a secret only you and Bondify know. No call back to api.bondify.dev is required to trust a login. Here's how that's possible, and what it buys you.

The flow

1. Create a session
   
   
   Your client calls the public generate endpoint (or your server calls the secret-key version). Bondify returns a deeplink, a session_token, and an expires_at.




2. Open Telegram
   
   
   The client opens the deep link — https://t.me/<your_bot>?start=<session_token> — and the user lands in your bot.




3. Confirm in Telegram
   
   
   The user taps Confirm. Bondify marks the session confirmed and attaches the Telegram identity to it.




4. Detect confirmation
   
   
   Your client polls verify (the SDK does this for you), or your server polls it, or — better — you skip polling entirely and let a webhook push the result to you.




5. Verify on your backend
   
   
   The verify response includes a signed proof. Your server checks the signature locally. If it's valid, you mint your own session — cookie, JWT, whatever you already use.

Step 5 is the part worth dwelling on, because it's where the "no round-trip" property actually comes from.

What's inside a proof

A proof is a JWT, signed with HS256. Decode it and you get something like:

{

  "telegram_id": "123456789",

  "telegram_name": "Ada Lovelace",

  "telegram_username": "ada",

  "project_id": "proj_xxxxxxxx",

  "session_token": "a1b2c3d4e5f6",

  "iss": "bondify",

  "iat": 1700000123,

  "exp": 1700000423

}

Nothing exotic. The interesting part isn't the payload — it's the signature. The token is signed with your project's webhook secret (whsec_…):

HS256(header.payload, webhook_secret)

The proof is signed with the webhook secret, not the secret key (sk_…). The same whsec_… verifies both proofs and webhook signatures, so your backend only needs to manage one secret for both flows.

Because only your server and Bondify know whsec_…, a valid signature is proof (hence the name) that Bondify issued the token and that nobody tampered with the payload in transit. Your server can check this with one line of JWT-library code and zero network calls:

import { BondifyServer } from '@bondify/node'



const bondify = new BondifyServer({

  jwtSecret: process.env.BONDIFY_WEBHOOK_SECRET!,

})



const user = await bondify.verifyProof(proof)

// user.telegram_id, user.telegram_name, user.telegram_username

That's the entire trust boundary. No HTTP client, no timeout handling, no "what if Bondify's API is slow right now" — just a synchronous cryptographic check that either passes or throws.

Why this matters more than it sounds like it should

It's tempting to read "saves one HTTP call" and shrug. In practice it changes three things:

• 
  Latency is bounded by your own infrastructure, not ours. Your login endpoint's p99 no longer includes a leg to a third-party API. If Bondify has a bad five minutes, sessions that already reached confirmed still verify — because verification never asked Bondify in the first place.


• 
  There's one fewer thing that can go down in your critical path. A network partition between your backend and Bondify's API doesn't fail logins that have already produced a proof.


• 
  The security boundary is auditable in isolation. "Is this login real?" reduces to "does this HMAC check pass with this secret?" — a property you can unit test without mocking an HTTP client.

This is the same reason JWTs displaced server-side session lookups in a lot of API design: shifting verification from ask the source of truth to check a signature from the source of truth turns a remote dependency into a local computation.

The properties that make it safe to do this

Self-contained tokens are only as trustworthy as their constraints. Bondify's proof has three:

It expires fast

A proof's exp is 5 minutes after issuance. Standard JWT libraries reject it automatically once expired, so "verify promptly" isn't a suggestion you have to remember — it's enforced by the format. Don't cache a proof and check it later; check it the moment you receive it.

It's single-use

A session can be read once via the verify endpoint. The first confirmed read flips it to used, and it will never produce another proof after that. There's no scenario where the same proof gets handed to two different backends and both accept it.

The signing secret never touches the browser

The webhook_secret and secret_key live only on your server. The browser only ever sees the public project_id, which can start a session but cannot verify proofs or call management endpoints. Even if someone inspects your frontend's network tab, there's nothing there to forge a proof with.

A proof that passes signature verification is sufficient to trust the Telegram identity inside it — you don't need to call Bondify's API again to "double check." Re-verifying server-side adds latency without adding security, since the HMAC already proves provenance.

Where webhooks fit in

Polling step 4 above works, but for most backends a webhook is the better default: Bondify pushes the confirmed identity to your endpoint the moment it happens, signed the same way (X-Bondify-Signature, HMAC-SHA256 over the raw body, same whsec_…). No proof JWT is involved there — the webhook carries the identity directly, and the signature is the trust mechanism. We'll cover the delivery and retry semantics in a follow-up post.

What Bondify intentionally doesn't store

The stateless design extends to data retention. Bondify keeps Telegram identity (telegram_id, telegram_name, telegram_username), session metadata, and — only if you've enabled phone collection on Pro/Business — telegram_phone. No passwords, no OAuth tokens, nothing your backend doesn't already need to make its own decision about who the user is.

If you're integrating this for the first time, the quickstart walks through generating a session and verifying a proof end to end in about fifteen minutes.