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

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 shape of the problem

A typical messenger-auth flow has five actors: your frontend, your backend, Bondify's API, Bondify's Telegram bot, and the user's Telegram client. Somewhere in that chain, something has to assert "this Telegram account confirmed this login" in a way your backend can trust.

The naive design makes your backend ask Bondify: "is session abc123 confirmed, and if so, by whom?" That works, but it means every login on every one of your users now depends on a synchronous call to a third party, at the exact moment your own auth is on the critical path.

The alternative is to make the assertion self-contained and verifiable offline — which is exactly what a signed JWT is for.

The flow

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:

1{
2  "telegram_id": "123456789",
3  "telegram_name": "Ada Lovelace",
4  "telegram_username": "ada",
5  "project_id": "proj_xxxxxxxx",
6  "session_token": "a1b2c3d4e5f6",
7  "iss": "bondify",
8  "iat": 1700000123,
9  "exp": 1700000423
10}

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

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:

1import { BondifyServer } from '@bondify/node'
2
3const bondify = new BondifyServer({
4  jwtSecret: process.env.BONDIFY_WEBHOOK_SECRET!,
5})
6
7const user = await bondify.verifyProof(proof)
8// 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.

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.