Telegram login

Besides an email code, a person can sign in through Telegram. This page describes what happens inside the Fidmos window when this method is chosen: which requests go out and what errors can occur.

Note

These requests are made by the window application (loaded via sdk.js), not your backend and not your code on the page. As a partner you do not need to call them directly — you get a single result, an authorization code, in onSuccess (see login widget). This page is here to help you understand the flow and read its errors.

How sign-in goes

1. The person confirms sign-in in Telegram. The window opens the Telegram widget; after confirmation it sends the Telegram data for verification — POST /api/v1/embed/telegram:

   POSThttps://id.fidmos.com/api/v1/embed/telegram

   Content-Type: application/json
   
   { "flow_id": "...", "id": 12345678, "auth_date": 1717000000, "hash": "...",
     "first_name": "Jane", "username": "jane" }

   The server verifies the signature of the data (hash) with the bot’s secret. If it does not match — telegram_invalid.

2. The identity is linked to a user. If this Telegram is already linked to a user, the flow is ready for completion:

   { "status": "authenticated", "completion_handle": "..." }

   If the Telegram is not linked to anyone yet, the window gets identity_unlinked and creates a new user — POST /api/v1/embed/identity/create with the same flow_id:

   { "status": "authenticated", "completion_handle": "..." }

3. The window completes sign-in — it exchanges completion_handle for an authorization code (POST /api/v1/embed/complete) and hands it to your page via onSuccess. Next — the usual code-for-token exchange.

Errors of this flow

All error responses come in the envelope { "error": "<code>" }. The code meanings and the general breakdown are in the error reference.

Code	When
telegram_invalid	the Telegram data failed the signature check
no_pending_identity	there is no pending sign-in method to create a user from
identity_taken	this Telegram was linked to another user in the meantime
invalid_completion	the flow completion failed (HTTP 409)
authorization_failed	the window could not issue an authorization code
flow_expired	the flow was not found or has expired
parent_origin_mismatch	the request came from a foreign origin

Tip

For you the outcome is the same with any sign-in method — an authorization code and, after the exchange, a pairwise sub. The email code flow is on the email code login page, wallet — wallet login.