> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axottle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entrance via Telegram

> Connecting Telegram as a way of entering the support panel and portal: setting up the provider, linking accounts, diagnostics.

Telegram can be used as a way to log into the Axottle panel and the support portal - instead of a password or with it. [Log In With Telegram](https://core.telegram.org/bots/telegram-login).

> [!NOTE]
>
> For whom: Dashboard administrator with the right **Manage users**.
> What you need: access to [@BotFather](https://t.me/BotFather) and the domain on which the panel works.

> [!WARNING]
>
> There is no self-registration; only the person to whom the administrator has created an account in advance and attached a Telegram account can log in via Telegram, and an unfamiliar Telegram account will be refused, even if the provider is configured.

## Step 1: Set up the provider

The setup is performed once for the entire installation.

**1. Open the authentication section**

Go to **Settings → Authentication**. It is the Telegram login that is configured here – not to be confused with **Settings → Telegram**, where the panel notification bot lives.

**2. Copy the Callback URL**

In the **card, Telegram** login has a **Callback URL** with the Copy button. This address will need to be specified in BotFather.

**3. Create a Login App in BotFather**

Open [@BotFather](https://t.me/BotFather), create a sign-in application, specify the panel domain and the copied Callback URL. BotFather will issue **Client ID** and **Client Secret**.

**4. Fill in the fields in the panel**

Insert Client ID and Client Secret, turn on the **Switch Enable Sign-in via Telegram** and press **Save**.

After saving the entry screens, the button **Enter via Telegram**. While the provider is turned off or not completely filled, the button is not shown.

> [!NOTE]
>
> Client Secret is stored in a secure secret repository and is never returned via the API. When re-editing, leave the field blank to keep the current secret.

## Step 2: Linking Telegram to your account

As long as you don't have a Telegram attached to your account, you can't log in through it. There are three ways to link it.

### Your account.

**1. Open accounts.**

Go to **Settings → Accounts**.

**2. Tie up Telegram.**

In the card **Entrance via Telegram** press **Attach Telegram**.

**3. Confirm in Telegram**

You'll be redirected to Telegram. Once confirmed, the panel will take you back and show "Telegram tied."

> [!WARNING]
>
> For a protected superuser, binding and decoupling require re-entering the password (and the 2FA code, if enabled) – this cannot be done “by inertia” from an already open session.

### A new user immediately from Telegram

In the **wizard Add the user** (see [Accounts and login](https://docs.axottle.com/en/panel/access-and-sessions.md)) fill in the field **Telegram User ID**. Password can not be set - then the user will only log in via Telegram.

### Support operator from Telegram

In **Support → Operators** operator can be added by Telegram-nickname or ID. The panel creates a full-fledged user Axottle with a tied Telegram and support role — a separate “accountless” entity is no longer. More: [Operators and roles](https://docs.axottle.com/en/support/operators.md).

## What does the entrance look like?

1. On the entrance screen, click **Log in via Telegram**.
2. Confirm the entrance to Telegram.
3. The panel will check Telegram's response on its side and open the session.

The same procedure works on the support portal (`/support-panel`).

## Telegram's unbundling

In the card **Entrance via Telegram** press **Untie Telegram**.

> [!NOTE]
>
> You can't remove the only way you're logging in. If you don't have a password, the panel will fail -- you need to set the password first.

## Diagnostics

If the input fails, the panel returns to the login screen and shows the reason. The full message is duplicated in the panel logs.

| What is shown by | Cause of | What to do with | |
| - | - | - | - |
| Login session expired or did not match | Lasted more than 10 minutes, the panel restarted or did not return the service cookie | Repeat login. If it repeats - check the Callback URL with the | panel address |
| Telegram has not confirmed the authorization code | Do not match Client ID, Client Secret or Callback URL | Check all three fields in **Settings → Authentication** | |
| This Telegram account is not tied to any | user Login tries to execute an unbound account | Create a user and link Telegram | to it |
| This Telegram account is already linked to another | user One Telegram - one user of | Untie Telegram from a former user or use another account | |
| Account disabled | User in the "Disconnected" status | Enable an account in the user list | |
| Sign in via Telegram not configured | Provider turned off or filled not completely | Complete setting provider | |

Logs of the panel on attempts to enter:

```bash theme={null}
journalctl -u axottle --since "10 min ago" | grep -i telegram
```

> [!TIP]
>
> The most common reason is a Callback URL, which does not match the panel address by host or schema. It should be exactly the same as shown in **Settings → Authentication**.

## What's going on under the hood

* Authorization Code Flow with PKCE is used: the authorization code changes to a token on the server side, it does not get into the browser.
* Telegram’s response is verified by signature (JWKS), publisher, recipient, expiration date and disposable `nonce`.
* The service values of `state` and `PKCE verifier` are disposable and live for 10 minutes.
* The session is issued as a `HttpOnly` cookie – the token is not available from JavaScript.

Read more about Entry Protection: [Entry Protection](https://docs.axottle.com/en/security/authentication.md).

## Verification

> [!TIP]
>
> The button **Sign in via Telegram** is visible on the login screen, the attached user logs in without a password, and the unbound Telegram account is refused with an understandable message.

## Rollback

* Turn off the switch in **Settings → Authentication** – the login button will disappear, the bindings will remain.
* You can untie Telegram from a specific user in his card (if he has a password).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.