# Authentication⚓︎

The library supports three ways to authenticate a bot on TrueConf Server:

| Method | API | When to use it |
| --- | --- | --- |
| Token | `Bot(server, token=...)` | You already have a token obtained manually or through the API |
| Login and password | `Bot.from_credentials(...)` | Login and password authentication is enabled on the server |
| OAuth2 | `Bot.from_oauth(...)` | Login and password authentication is disabled on the server |

## Token authentication⚓︎

Obtain a token as described in the official API documentation.

We recommend storing the token in an environment variable or a `.env` file. If you use a public repository, remember to add `.env` to `.gitignore`.

```
from os import getenv

TOKEN = getenv("TOKEN")
bot = Bot(server="video.example.com", token=TOKEN, dispatcher=dp)
```

Note

A token is valid for one month from the time it is created. However, an authenticated connection remains active until it is closed, even after the token expires. In theory, such a connection can remain active for years.

## Login and password authentication⚓︎

The `Bot.from_credentials()` method authenticates the bot with a login and password:

```
bot = Bot.from_credentials(
username="echo_bot",
password="123tr",
server="video.example.com",
dispatcher=dp,
)
```

Info

Every call to from_credentials() requests a new token from the server. Each token is valid for one month.

The main parameters after `password` are keyword-only:

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `dispatcher` | `Dispatcher` | `None` | Dispatcher used to register handlers |
| `receive_unread_messages` | `bool` | `False` | Whether to receive messages that arrived while the bot was offline |
| `receive_system_messages` | `bool` | `False` | Whether to receive system messages |
| `skip_self_messages` | `bool` | `True` | Whether to ignore messages sent by the bot itself |
| `verify_ssl` | `bool | str | ssl.SSLContext` | `True` | SSL certificate verification settings |
| `https` | `bool` | `True` | Whether to use HTTPS |
| `web_port` | `int` | `None` | WebSocket port (`443` with HTTPS and `4309` without HTTPS by default) |
| `ws_max_retries` | `int` | `5` | Maximum number of connection attempts after network errors |
| `ws_max_delay` | `int` | `60` | Maximum delay between connection attempts, in seconds |
| `timeout` | `float | int` | `10.0` | Server response timeout |
| `on_health_check` | `Callable` | `None` | Callback invoked when the connection state changes |

For the complete parameter list, see the `Bot.from_credentials()` reference.

If login and password authentication is disabled on the server, the method raises `PasswordAuthDisabledError`. Use `Bot.from_oauth()` instead.

## OAuth2 authentication⚓︎

If login and password authentication is disabled on the server for security reasons, the bot cannot use `from_credentials()`. It does not support authentication through NTLM, Kerberos, other SSO protocols, or MFA.

In this case, create an OAuth application on the server and authenticate the bot with `Bot.from_oauth()`. In addition to the login and password, you need the application's `client_id`:

```
bot = Bot.from_oauth(
username="elisa",
password="123tr",
client_id="application_client_id",
server="video.example.com",
dispatcher=dp,
)
```

Requirements:

- TrueConf Server 5.5.3 or later;

- an OAuth application created on the server;

- at least one scope configured for the application. The `version:read` scope is sufficient and does not expose sensitive information. A token cannot be obtained for an application without a scope.

`Bot.from_oauth()` accepts the same parameters as `from_credentials()` and additionally requires `client_id`. See the `Bot.from_oauth()` reference.

### Authentication errors⚓︎

| Exception | When it occurs | What to do |
| --- | --- | --- |
| `PasswordAuthDisabledError` | The server rejects the token request with `403 auth_method_disabled` because login and password authentication is disabled | Use `Bot.from_oauth()` |
| `OAuthMissingScopeError` | The server rejects the OAuth token request with `400 invalidScope` because the OAuth application has no configured scope | Add a scope, such as `version:read`, to the application settings on the server |

Both exceptions inherit from `TrueConfChatBotError` and can be imported from `trueconf.exceptions`. For details, see the exceptions reference.

October 1, 2026

October 1, 2026