rtk-vats-api

REST API on top of the internal API of the Rostelecom Virtual PBX personal account (cloudpbx.rt.ru/webapi). Lets scripts and AI agents manage telephony: contacts, subscribers, call groups, call history, call recordings, numbers and routing, balance — plus a transparent proxy to any of the ~240 VPBX endpoints.

Login uses the "Rostelecom Passport" username and password with SMS code confirmation; the session is then maintained automatically. An MCP server and a ready-made skill are included so an AI agent (Claude Code and compatible tools) can use it.

Unofficial project: uses the internal personal account API, which Rostelecom may change without notice. Not affiliated with PJSC "Rostelecom".

How it works

• Login — with "Rostelecom Passport" username and password plus a one-time SMS code (POST /auth/login → POST /auth/code). After that the service runs on its own: JWT ~24 minutes, a background keepalive refreshes it via the refresh token.

• The session is stored in data/session.json (permissions 600) and survives service restarts.

• Access to this API is via the X-API-Key header (value in .env).

Why a browser engine is needed for login

For domains connected to "Rostelecom Passport", the classic POST /webapi/auth (username + password + domain) does not work: such an account has no password of its own in the VPBX, and the server responds "The entered credentials are incorrect". Login goes through the chain /webapi/sso → Keycloak passport.rt.ru → SMS code → return to the personal account with tokens.

Passport pages are protected by the F5 antibot: a regular HTTP client gets a JS challenge instead of the form, and grant_type=password (ROPC) gets the same challenge. That is why the login step is performed by a real engine (Playwright, Chromium) — only at the moment of login, for about thirty seconds. All further work uses plain httpx without a browser.

If you do not want to install Chromium on the server, there are two options: scripts/login_helper.py (the browser runs on your machine, tokens are sent to the service) or manual POST /auth/import.

Related MCP server: Radius MCP Server

Running (development)

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/playwright install chromium     # нужен только для /auth/login
cp .env.example .env                      # заполнить PBX_USERNAME/PBX_PASSWORD, API_KEY
.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8010

OpenAPI documentation: http://<host>:8010/docs

Authorization

KEY="X-API-Key: <ваш API_KEY>"

# 1. Логин и пароль -> на телефон владельца учётки уходит SMS
curl -X POST http://localhost:8010/auth/login -H "$KEY" \
     -H 'Content-Type: application/json' \
     -d '{"username":"lk_1234567890","password":"..."}'
# -> {"status":"code_required","hint":"Мы отправили код на номер +7 ...","seconds_to_enter_code":300}

# 2. Код из SMS
curl -X POST http://localhost:8010/auth/code -H "$KEY" \
     -H 'Content-Type: application/json' -d '{"code":"123456"}'
# -> {"status":"ok","seconds_left":1435,"has_refresh_token":true,"has_fingerprint":true}

# Состояние сессии / принудительное обновление / отмена входа
curl http://localhost:8010/auth/status -H "$KEY"
curl -X POST http://localhost:8010/auth/refresh -H "$KEY"
curl -X POST http://localhost:8010/auth/cancel  -H "$KEY"

The username and password can be omitted from the request — then PBX_USERNAME / PBX_PASSWORD are taken from .env. Login with a one-time code without a password: {"by_code": true}.

You have BROWSER_CODE_TTL seconds to enter the code (300 by default): the open Passport page waits for the code for all that time. If you did not make it — start over with /auth/login.

Login without a browser on the server

# на своей машине (там, где есть playwright); токены уедут на удалённый сервис
python scripts/login_helper.py --api-url http://10.10.0.187:8010 --api-key <KEY>

Manual token import (last resort)

DevTools (F12) → Application → Local Storage → token, refreshToken. The fingerprint value is absent from storage — take it from the SSO redirect address bar (...&fingerprint=...) or run getBrowserFingerprint() in the personal account console. Without fingerprint, session refresh will not work.

curl -X POST http://localhost:8010/auth/import -H "$KEY" \
     -H 'Content-Type: application/json' \
     -d '{"token":"<JWT>","refresh_token":"<refreshToken>","fingerprint":"<fp>"}'

Domains without SSO

If the account has its own password in the VPBX itself, the classic login works: POST /auth/start (username/password/domain from .env) → POST /auth/complete with the SMS code.

Endpoints

Convenient (typed)

Transparent proxy

Any VPBX endpoint is available via ANY /proxy/{path} → /webapi/{path} (query, body, and method are passed through; binary responses are returned as-is):

curl http://localhost:8010/proxy/domain/payments/balance -H "$KEY"
curl -X POST http://localhost:8010/proxy/callcenter/reports/by_calls \
     -H "$KEY" -H 'Content-Type: application/json' -d '{"date_from":"2026-08-01"}'

The VPBX endpoint map (auth, domain/, callcenter/, user/*, meetings, ivr …) — in the personal account source lk_new/assets/index-*.js (grep for callApi("/...).

Tests

.venv/bin/python -m pytest -q

Mocks via respx, no real requests to the VPBX.

Skill for AI models

MCP server (mcp_server/)

The rtk-vats MCP server (stdio) with typed vats_* tools — connects to any agent with MCP support (Kimi Code, Claude Code/Desktop, Cursor). It talks to this REST API over HTTP, so it runs on the agent's machine:

{
  "mcpServers": {
    "rtk-vats": {
      "command": "/path/to/rtk-vats-api/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/rtk-vats-api",
      "env": {
        "VATS_API_URL": "http://10.10.0.187:8010",
        "VATS_API_KEY": "<тот же API_KEY>"
      }
    }
  }
}

Tools: vats_auth_login/code/status/refresh/cancel, vats_contacts_*, vats_domain_users, vats_users_list, vats_groups_list, vats_calls_history, vats_call_protocol, vats_call_record (downloads to VATS_DOWNLOAD_DIR, ./downloads by default), vats_balance, vats_numbers, vats_settings, vats_proxy (any VPBX endpoint).

SKILL.md (skills/rtk-vats/)

A ready-made skill for CLI agents (Claude Code / Kimi Code and compatible): login flow (username/password → SMS), endpoints, security rules, and the references/pbx-setup.md reference for PBX configuration (subscribers, groups, IVR, schedules). Installation — copy or symlink skills/rtk-vats/ into the agent's skills directory (project .kimi/skills/, .claude/skills/, or user-level).

Deployment (Docker)

cp .env.example .env      # заполнить PBX_USERNAME/PBX_PASSWORD, API_KEY
docker compose up -d --build
docker compose logs -f

The default image includes Chromium for Passport login. A lightweight variant without it — docker build --build-arg WITH_BROWSER=0 -t rtk-vats-api:slim .; then login is performed externally (scripts/login_helper.py) or via /auth/import.

⚠️ Keep port 8010 on the local network or behind a VPN and do not publish it to the internet: a live session of your PBX lives behind it. The API_KEY is the only protection of the service itself.

Security

• Passwords, SMS codes, and tokens are not logged; .env and data/ are in .gitignore.

• PBX_VERIFY_SSL=false — only for machines behind a corporate MITM proxy (otherwise the certificate chain will not validate). Leave true on the server.

• The second factor is not bypassed: a human enters the SMS code, once per session.

• An unfinished login attempt is closed by a timeout — the browser does not stay hanging.

If RTK changes the API

There is a single place to edit: app/pbx_client.py (authorization/refresh) plus the corresponding router in app/routers/. The /proxy/* proxy will keep working as long as the path scheme itself does not change.