Telegram sign-in

Telegram sign-in in Nautilus is the Passepartout API (/v1/passepartout/*, for API keys with the passepartout scope): a managed service that lets your end-users sign in with a single tap in Telegram, with no passwords, email verification or reset flows to build or maintain. This section calls it Passepartout wherever it names the API.

What is Passepartout?

Passepartout gives your tenants' applications a drop-in login flow backed by Telegram. Your app starts a login, sends the user to a Telegram deep link, and polls for completion to receive an access token representing the authenticated user.

Under the hood, a high-performance Rust bridge long-polls each tenant's Telegram bot, verifies the update, and provisions a tenant-scoped identity in Ory Kratos. Bot tokens are encrypted at rest with AES-256-GCM, and every end-user identity is isolated per tenant — one Telegram user signing into two tenants results in two independent identities.

Why Passepartout?

CapabilityDescription
PasswordlessUsers authenticate through Telegram — nothing to store, leak, or reset.
Tenant-scoped identitiesEnd-users are namespaced per tenant in a shared Kratos identity store.
Drop-in bot setupCreate a bot with @BotFather, paste the token in the dashboard, enable it.
No public webhookThe bridge uses Telegram long-polling — nothing to expose or secure.
Encrypted tokensBot tokens are encrypted at rest with AES-256-GCM.
Multi-language SDKsFirst-class passepartout resource in the Node, PHP, Python, and Rust SDKs.

How the login flow works

  1. Your app calls login/start with a Passepartout API key and receives a nonce and a deep_link.
  2. You send the end-user to the deep_link — Telegram opens your bot with /start <nonce>.
  3. Your app polls login/status with the nonce until status becomes completed.
  4. The completed response carries an access_token and the Telegram user — the user is signed in.
  5. Optionally, validate a token later with tokens/introspect. A user you have deactivated gets no token at login, and their existing tokens introspect as inactive until you reactivate them.

Quick Start

  1. In the Dashboard, create a Telegram bot with @BotFather, paste its token, and enable it.
  2. Create an API key on the Keys page with Telegram sign-in ticked.
  3. Start a login and send the user to Telegram:
# 1. Start a login — returns a nonce and a Telegram deep link
curl -X POST https://api.vernesoft.com/v1/passepartout/login/start \
  -H "Authorization: Bearer vrn_9f8a7..."
# => { "nonce": "n_9f2c…", "deep_link": "https://t.me/your_bot?start=n_9f2c…", "expires_at": "…" }

# 2. Poll for status until the user taps Start in your bot
curl "https://api.vernesoft.com/v1/passepartout/login/status?nonce=n_9f2c…" \
  -H "Authorization: Bearer vrn_9f8a7..."
# => { "status": "completed", "access_token": "ppt_live_…", "user": { "id": "…" } }

That's it — Passepartout runs the bot bridge, provisions the identity, and issues the token.

See the API Reference for every endpoint and the full SDK surface.