Log In With Telegram

Telegram offers app and website developers a free and open platform that lets over 1 billion users seamlessly sign up and log in with their Telegram accounts.

Benefits of Telegram Login

• Higher conversion
  Users sign in with a few taps, boosting conversion and retention.

• Lower verification costs
  Users can share their verified phone number, removing the need for expensive codes.

• Direct communication channels
  You can reach your users within Telegram, with built-in push notification support.

• Further integration
  You can deliver more services directly via the Bot API and Mini Apps.

Note: This document describes the Telegram Login library and the new OpenID Connect login flow.
The legacy iframe-based JavaScript widget documentation is archived here.

Getting Started

Telegram offers a compact tool to quickly add Telegram login buttons to your interface. You can also directly access our library's JS API.

Alternatively, Telegram supports the standard OpenID Connect protocol. This allows you to integrate Telegram authentication into your application using any OIDC-compatible library or authentication platform (e.g., Keycloak, Authentik, Auth0 etc.).

Our implementation follows the standard Authorization Code Flow with PKCE support.

For an in-depth understanding of the general OIDC flow, please refer to the OpenID Foundation's Developer Guide.

TL;DR

• Set up a bot to represent your application.
• Register your Allowed URLs via @BotFather and obtain your Client ID and Secret.
• Add the Telegram Login library to your page
• Validate ID tokens to cryptographically verify incoming requests.

Alternatively, you can use an OpenID integration.

Having trouble with any of the steps above? Feel free to reach out to us at @BotSupport, making sure to include the hashtag #oidc in your message.

Setting up a bot

To use Telegram Login, you'll need a Telegram bot to represent your application.

We strongly recommend that the profile picture of the bot corresponds with your website's logo, and that the bot's name reflects that connection. Users will see a confirmation box similar to the one below when logging in:

Users are much more likely to authorize your app if the bot has a name and logo they recognize and expect. Official services can also apply for verification from Telegram or third parties for greater transparency.

Registering your Allowed URLs

Once you have chosen a bot, open the @BotFather mini app and navigate to Bot Settings > Web Login.

Add all Allowed URLs for your application. This includes the website origins where you embed the login widget (e.g., https://example.com) and specific redirect URIs for your OIDC flow (e.g., https://example.com/auth/callback). You can register multiple URLs to support different domains or endpoints.

In this section, @BotFather will also display your Client ID and Client Secret. Save these values securely – you will need them to configure your OIDC client.

Important: For security reasons, Telegram will only process logins or redirect users using your pre-registered URLs.

Using the Telegram Login library

Use the tool below to customize your button and get the HTML snippet for your website.

Alternatively, you can interact with the library using the following JS methods:

Available Methods

InitOptions

Callback Data

When the login flow completes, the callback may receive either a success payload (user data) or an error.

OpenID Connect

If you are using an OIDC-compatible library or identity broker, you can use the standard configuration values below.

Discovery Document URL

https://oauth.telegram.org/.well-known/openid-configuration

Client Configuration

Available Scopes

You can request specific permissions when initiating authorization. The openid scope is required.

User Data Structure

All requested user information is returned directly in the ID token. After successful authentication, the decoded ID token will look like this:

{
  "iss": "https://oauth.telegram.org",
  "aud": "123456789",
  "sub": "1234123412341234123",
  "iat": 1700000000,
  "exp": 1700003600,
  "id": 987654321,
  "name": "John Doe",
  "preferred_username": "johndoe",
  "picture": "https://cdn4.telesco.pe/file...",
  "phone_number": "971577777777"
}

Note that Telegram does not currently provide a separate UserInfo endpoint. However, some OIDC libraries may expect this endpoint by default, and you may need to configure them to skip a separate userinfo request.

Manual Implementation

If you are integrating the OIDC flow manually without a library, use the endpoints and flow details below.

Endpoints

• Authorization: https://oauth.telegram.org/auth
• Token: https://oauth.telegram.org/token
• Keys (JWKS): https://oauth.telegram.org/.well-known/jwks.json

Initiate Authorization

Direct the user to the authorization endpoint with the following parameters. This URL must be opened in the user's browser.

GET https://oauth.telegram.org/auth?
    client_id=<YOUR_BOT_ID>&
    redirect_uri=<YOUR_CALLBACK_URL>&
    response_type=code&
    scope=openid%20profile%20phone&
    state=<RANDOM_STRING>&
    code_challenge=<PKCE_CHALLENGE>&
    code_challenge_method=S256

• client_id: Client ID provided by BotFather.
• state: A random string generated by your backend to prevent CSRF.
• code_challenge: Base64URL-encoded SHA256 hash of your code verifier (PKCE).

Exchange Code for Tokens

If the user approves the login, they will be redirected to your redirect_uri with a code parameter. Exchange this code for an access token and ID token by making a server-side POST request.

This request requires Basic Authorization using your Client ID and Client Secret (base64(client_id:client_secret)).

POST https://oauth.telegram.org/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <BASE64_CREDENTIALS>

grant_type=authorization_code&
code=<AUTHORIZATION_CODE>&
redirect_uri=<YOUR_CALLBACK_URL>&
client_id=<YOUR_BOT_ID>&
code_verifier=<PKCE_VERIFIER>

Response:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJ..."
}

Validating ID Tokens

The id_token is a signed JSON Web Token (JWT). Before trusting the user data inside, you must validate the signature:

1. Fetch Keys: specific public keys from the JWKS endpoint.
2. Verify Signature: Ensure the token was signed by Telegram.
3. Verify Claims: Check that iss is https://oauth.telegram.org, aud matches your Bot ID, and the token has not expired (exp).

Once you have established a connection with the user, you can optionally use your linked bot to provide services directly in the chat interface via the Bot API, or seamlessly offer your entire web application inside Telegram using Mini Apps.