StaticGramBot API

StaticGram Login

StaticGram Login позволяет сайту или приложению авторизовать пользователя его аккаунтом StaticGram. Пользователь подтверждает вход в приложении StaticGram или по номеру телефона, а сайт получает его id, имя, username, аватар и, если пользователь согласится, номер телефона. Провайдер входа работает на https://oauth.staticgram.top.

Вход всегда привязан к боту. Бот выступает OIDC-клиентом: Client ID равен id бота, адреса сайта регистрируются в @BotFather. Есть три способа подключения:

СпособЧто получает сайтКогда выбирать
Виджет staticgram-widget.jsполя id, first_name, …, hash (классический формат) или id_tokenготовая кнопка «Войти через StaticGram», минимум кода
JS SDK staticgram-login.jsid_token (JWT), по желанию также классические полясвоя кнопка, запрос телефона и права писать от бота
OpenID Connect (authorization code + PKCE)id_token через серверный обмен кодасерверная авторизация, готовые OIDC-библиотеки, нативные приложения

Кроме того, бот может отправить пользователю кнопку login_url: вход на сайт по нажатию в чате, без виджета.

Адреса

НазначениеАдрес
Issuer (iss)https://oauth.staticgram.top
Discoveryhttps://oauth.staticgram.top/.well-known/openid-configuration
Ключи подписи (JWKS)https://oauth.staticgram.top/.well-known/jwks.json
Авторизация (страница входа)GET https://oauth.staticgram.top/auth
Обмен кодаPOST https://oauth.staticgram.top/token
Проверка сессииPOST https://oauth.staticgram.top/introspect
Виджетhttps://oauth.staticgram.top/staticgram-widget.js (также https://staticgram.top/js/staticgram-widget.js)
JS SDKhttps://oauth.staticgram.top/staticgram-login.js (также https://staticgram.top/js/staticgram-login.js)
Старые адреса на staticgram.top

Раньше провайдер входа работал на https://staticgram.top (/auth, /token и т.д.). Эти адреса сохранены для совместимости, но в новом коде используйте oauth.staticgram.top. Проверяйте iss по значению issuer из discovery: в новых токенах это https://oauth.staticgram.top.

Настройка бота в @BotFather

  1. Создайте бота (/newbot) или возьмите существующего.
  2. Отправьте /setlogin и выберите бота. При первом запуске BotFather включит вход и пришлёт Client ID (это id бота) и Client Secret. Секрет показывается один раз, сохраните его. Сервер хранит только хеш, восстановить секрет нельзя, можно только выпустить новый.
  3. В том же диалоге зарегистрируйте адреса командами (по одной или до 32 строк в одном сообщении) и закончите /done. Изменения применяются сразу, /cancel закрывает диалог без отката уже применённых команд.
Команды /setlogin
add origin https://example.com
add redirect https://example.com/auth/callback
add ios com.example.app ABCDE12345 exampleapp://sglogin Example iOS App
add android com.example.app AA:BB:...:FF exampleapp://staticgram-login Example Android App
remove origin https://example.com
remove redirect https://example.com/auth/callback
remove app 12
algorithm RS256|ES256|EdDSA|ES256K
enable
disable
КомандаЗначение
add origin <origin>Origin сайта (https://host[:port] без пути), на котором работают виджет, JS SDK и кнопки login_url. Сравнивается точно: https://example.com и https://www.example.com регистрируются отдельно.
add redirect <url>Точный адрес возврата для серверного OIDC (redirect_uri). Без логина/пароля и фрагмента, без параметров code, state, error, error_description в query. Пустой путь приводится к /, порт 443 отбрасывается, хост переводится в нижний регистр.
add ios <bundle_id> <team_id> <callback> <название>Нативное iOS-приложение: Bundle ID, 10-символьный Team ID, адрес возврата и отображаемое название (до 128 символов). См. Нативные приложения.
add android <package> <sha256> <callback> <название>Android-приложение: имя пакета и SHA-256 отпечаток сертификата подписи (64 hex-символа, двоеточия допускаются).
remove origin|redirect <url>, remove app <id>Удаление адреса или приложения (номер приложения есть в /logininfo).
algorithm <alg>Алгоритм подписи новых id_token. По умолчанию RS256. Сейчас на сервере есть ключи для RS256, ES256 и EdDSA (список в id_token_signing_alg_values_supported); ES256K принимается командой, но без ключа BotFather ответит, что алгоритм недоступен. С EdDSA (и ES256K) разрешён только scope openid, то есть без профиля и телефона.
enable / disableВключить или выключить вход. После disable новые запросы отклоняются, а незавершённые нельзя подтвердить или обменять.

Остальные команды:

  • /logininfo: Client ID, статус, алгоритм подписи, версия секрета, зарегистрированные адреса и приложения.
  • /resetloginsecret: выпустить новый Client Secret. Старый перестаёт действовать сразу, новый показывается один раз.
Только HTTPS

Адреса http:// на сервере не принимаются. Для локальной разработки используйте туннель с HTTPS.

Как пользователь входит

Виджет, JS SDK и серверный OIDC ведут пользователя на страницу входа https://oauth.staticgram.top/auth. Заголовок страницы: «Вход на {домен}», под ним «{имя бота} запрашивает доступ через StaticGram». Войти можно тремя способами.

  1. На телефоне. Кнопка «Открыть StaticGram» открывает приложение сразу на окне подтверждения. Пользователь нажимает «Разрешить», и страница завершает вход сама.
  2. На компьютере, по номеру. Пользователь вводит номер телефона StaticGram в международном формате (+888…, +1… и т.д.). Если номер зарегистрирован, от официального аккаунта StaticGram приходит сообщение «Запрос на вход на {домен} ({бот}) с IP …, страна, браузер …» с кнопками «Подтвердить» и «Отклонить». После подтверждения страница входит автоматически. Запрос можно подтвердить и в окне подтверждения приложения.
  3. По QR-коду. Кнопка «Показать QR-код» выводит код, который сканируют камерой телефона или сканером в StaticGram; дальше подтверждение как на телефоне.
  • Страница не сообщает, существует ли введённый номер: ответ одинаковый в обоих случаях.
  • Запрос на вход действует 5 минут и одноразовый. Частота запросов ограничена по IP и по номеру телефона.
  • В окне подтверждения пользователь видит бота, домен (или приложение), браузер, платформу, IP и страну устройства, с которого начат вход. Если запрошены телефон или право писать от бота, их можно разрешить или не разрешить отдельно.
  • Каждый подтверждённый вход попадает в Настройки → Устройства (раздел «Активные сайты»): домен, бот, браузер, платформа, IP, регион, дата входа. Там вход можно завершить по одному или все сразу. Сайт узнаёт об этом через /introspect (authorization_active: false), а кнопки login_url снова потребуют подтверждения.

Виджет: кнопка «Войти через StaticGram»

Вставьте скрипт в то место страницы, где должна появиться кнопка. Скрипт добавит после себя обычную кнопку <button> (не iframe) с логотипом StaticGram и текстом «Войти через StaticGram» (на английском «Log in with StaticGram»), а по нажатию откроет окно входа.

Классический виджет
<script async src="https://oauth.staticgram.top/staticgram-widget.js"
        data-staticgram-login="example_bot"
        data-size="large"
        data-radius="10"
        data-request-access="write"
        data-onauth="onStaticGramAuth(user)"></script>
<script>
  function onStaticGramAuth(user) {
    // user: {id, first_name, last_name, username, photo_url, auth_date, hash}
    // Отправьте объект на сервер и проверьте hash (см. ниже).
    fetch("/login/staticgram", {method: "POST", headers: {"content-type": "application/json"}, body: JSON.stringify(user)});
  }
</script>

Вместо callback можно указать адрес, на который браузер перейдёт с данными в query-строке (GET):

Редирект на data-auth-url
<script async src="https://oauth.staticgram.top/staticgram-widget.js"
        data-staticgram-login="example_bot"
        data-auth-url="/login/staticgram"></script>
<!-- переход на /login/staticgram?id=…&first_name=…&auth_date=…&hash=… -->

Атрибуты

АтрибутЗначение
data-staticgram-loginUsername бота без @. Скрипт сам узнаёт Client ID через POST /staticgram-widget/resolve; это сработает, только если origin страницы зарегистрирован у бота (add origin). Нужен этот атрибут или data-client-id.
data-client-idClient ID (id бота). Без data-auth-url включает режим OIDC: callback получает {id_token, user}.
data-onauthГлобальная функция, например onStaticGramAuth(user), onStaticGramAuth или app.auth.done(user). Произвольный JavaScript не выполняется.
data-auth-urlАдрес для перехода с классическими полями в query. Должен быть на том же origin, что и страница (относительный путь или полный адрес своего сайта), иначе кнопка не сработает.
data-legacy1 или 0: принудительно включить или выключить классический формат. По умолчанию классический формат включён, если нет data-client-id или задан data-auth-url.
data-request-accesswrite: попросить у пользователя разрешение на сообщения от бота (scope staticgram:bot_access). Другие значения игнорируются; телефон через виджет не запрашивается, используйте JS SDK.
data-sizesmall, medium или large (по умолчанию).
data-radiusСкругление углов в пикселях, 0-64 (по умолчанию 8).
data-langЯзык кнопки: ru (по умолчанию, «Войти через StaticGram») или en («Log in with StaticGram»).

Атрибута data-userpic нет; кнопку можно дооформить своим CSS. Если вход не удался, кнопка снова становится активной, а причина видна в её подсказке (title). В классическом режиме callback при ошибке не вызывается; в режиме OIDC он получает {error: "…"}.

Данные пользователя в классическом формате

ПолеТипОписание
idIntegerid пользователя StaticGram
first_nameStringимя, есть всегда
last_nameStringфамилия, если указана
usernameStringusername, если есть
photo_urlStringпубличная ссылка на аватар; есть, только если у пользователя есть и фото, и username
auth_dateIntegerUnix-время подтверждения входа
hashStringподпись, см. следующий раздел

Отсутствующие поля в объект не попадают. У объекта, переданного в data-onauth, есть ещё неперечисляемое свойство id_token (JWT того же входа): в Object.keys и JSON.stringify оно не видно, поэтому код, который строит строку проверки из всех ключей объекта, продолжает работать.

Проверка авторизации (hash)

Классические данные StaticGram подписаны токеном бота. Проверяйте их только на сервере:

  1. data_check_string: все полученные поля, кроме hash, в виде key=value, отсортированные по ключу и соединённые символом \n (0x0A). Например: auth_date=1760000000\nfirst_name=Anna\nid=1780244143\nusername=anna.
  2. secret_key = SHA256(bot_token): именно SHA-256 от токена бота (сырые 32 байта), а не HMAC с "WebAppData", как в Mini Apps.
  3. Подпись верна, если hex(HMAC_SHA256(key=secret_key, msg=data_check_string)) совпадает с hash. Сравнивайте за постоянное время.
  4. Проверьте свежесть auth_date: например, отклоняйте данные старше суток, а для чувствительных действий старше нескольких минут. Сама подпись не устаревает.

Подпись зависит от текущего токена бота: после смены токена (/revoke в @BotFather) проверяйте новым токеном. Для кнопок login_url подпись делается токеном бота, указанного в кнопке. В примерах токен берётся из переменной окружения STATICGRAM_BOT_TOKEN.

Python
import hashlib, hmac, os, time

STATICGRAM_BOT_TOKEN = os.environ["STATICGRAM_BOT_TOKEN"]

def verify_staticgram_auth(data: dict, bot_token: str = STATICGRAM_BOT_TOKEN,
                           max_age: int = 86400) -> dict:
    data = {k: str(v) for k, v in data.items()}
    received = data.pop("hash", "")
    check_string = "\n".join(f"{k}={data[k]}" for k in sorted(data))
    secret = hashlib.sha256(bot_token.encode()).digest()
    expected = hmac.new(secret, check_string.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, received):
        raise ValueError("bad hash")
    if time.time() - int(data["auth_date"]) > max_age:
        raise ValueError("auth_date is too old")
    return data
Node.js
import crypto from "node:crypto";

export function verifyStaticGramAuth(data, botToken = process.env.STATICGRAM_BOT_TOKEN, maxAge = 86400) {
  const { hash = "", ...fields } = data;
  const checkString = Object.keys(fields).sort()
    .map((k) => `${k}=${fields[k]}`).join("\n");
  const secret = crypto.createHash("sha256").update(botToken).digest();
  const expected = crypto.createHmac("sha256", secret).update(checkString).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(String(hash));
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) throw new Error("bad hash");
  if (Date.now() / 1000 - Number(fields.auth_date) > maxAge) throw new Error("auth_date is too old");
  return fields;
}
PHP
function verifyStaticGramAuth(array $data, string $botToken, int $maxAge = 86400): array {
    $hash = (string)($data['hash'] ?? '');
    unset($data['hash']);
    ksort($data, SORT_STRING);
    $lines = [];
    foreach ($data as $key => $value) {
        $lines[] = $key . '=' . $value;
    }
    $secret = hash('sha256', $botToken, true);
    $expected = hash_hmac('sha256', implode("\n", $lines), $secret);
    if (!hash_equals($expected, $hash)) {
        throw new Exception('bad hash');
    }
    if (time() - (int)$data['auth_date'] > $maxAge) {
        throw new Exception('auth_date is too old');
    }
    return $data;
}
// $user = verifyStaticGramAuth($_GET, getenv('STATICGRAM_BOT_TOKEN'));
Go
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"net/url"
	"sort"
	"strconv"
	"strings"
	"time"
)

// botToken: os.Getenv("STATICGRAM_BOT_TOKEN")
func VerifyStaticGramAuth(q url.Values, botToken string, maxAge time.Duration) error {
	keys := make([]string, 0, len(q))
	for k := range q {
		if k != "hash" {
			keys = append(keys, k)
		}
	}
	sort.Strings(keys)
	lines := make([]string, len(keys))
	for i, k := range keys {
		lines[i] = k + "=" + q.Get(k)
	}
	secret := sha256.Sum256([]byte(botToken))
	mac := hmac.New(sha256.New, secret[:])
	mac.Write([]byte(strings.Join(lines, "\n")))
	expected := hex.EncodeToString(mac.Sum(nil))
	if !hmac.Equal([]byte(expected), []byte(q.Get("hash"))) {
		return errors.New("bad hash")
	}
	authDate, err := strconv.ParseInt(q.Get("auth_date"), 10, 64)
	if err != nil || time.Since(time.Unix(authDate, 0)) > maxAge {
		return errors.New("auth_date is too old")
	}
	return nil
}

JS SDK: staticgram-login.js

SDK даёт программный интерфейс StaticGram.Login и всегда возвращает подписанный id_token. Подключение:

HTML
<script src="https://oauth.staticgram.top/staticgram-login.js"></script>
<button id="login">Войти через StaticGram</button>
<script>
  StaticGram.Login.init({client_id: 1780244143, request_access: ["phone", "write"]}, function (data) {
    if (data.error) { console.warn(data.error); return; }
    // data.id_token: JWT, отправьте на сервер и проверьте подпись (см. «Проверка id_token»)
    // data.user: расшифрованный payload без проверки подписи, только для интерфейса
    fetch("/login/oidc", {method: "POST", headers: {"content-type": "application/json"},
                          body: JSON.stringify({id_token: data.id_token})});
  });
  document.getElementById("login").onclick = function () { StaticGram.Login.open(); };
</script>

Методы

МетодОписание
StaticGram.Login.init(options, callback)Сохраняет параметры и callback. Сам вход не начинает.
StaticGram.Login.open([callback])Открывает окно входа с параметрами из init. Вызывайте из обработчика клика, иначе браузер заблокирует всплывающее окно.
StaticGram.Login.auth(options, callback)То же без предварительного init.
StaticGram.Login.close()Закрывает окно; callback получит {error: "popup_closed"}.

Элементы с классом sg-auth-button вызывают StaticGram.Login.open() по клику. Инициализировать SDK можно атрибутами самого скрипта: data-client-id, data-request-access="phone write", data-lang, data-onauth="onAuth(data)" (строго в форме имяФункции(data)).

Автоинициализация
<script src="https://oauth.staticgram.top/staticgram-login.js"
        data-client-id="1780244143"
        data-request-access="phone write"
        data-onauth="onAuth(data)"></script>
<button class="sg-auth-button">Войти через StaticGram</button>

Параметры (options)

ПолеОписание
client_idОбязательно. Client ID (id бота).
request_accessМассив дополнительных прав: phone (номер телефона), write (бот сможет писать пользователю). Используется, если не задан scope; к нему всегда добавляются openid profile.
scopeЯвный список scope (строка через пробел или массив): openid, profile, phone, staticgram:bot_access (синоним write). openid добавляется автоматически.
nonceСтрока до 1024 символов, сгенерированная вашим сервером. Вернётся в claim nonce; сверяйте её, чтобы токен нельзя было подставить из другого входа.
legacytrue: дополнительно вернуть классические поля в data.auth_data (см. «Проверка авторизации»).
langЗарезервировано для языка интерфейса; страница входа сейчас всегда на русском.

Результат

Успех: {id_token, user, auth_data?}, где user это payload токена (claims из раздела Claims), auth_data есть только при legacy: true. Ошибка: {error}. Возможные значения:

errorПричина
access_deniedпользователь отклонил вход
temporarily_unavailableзапрос истёк (5 минут) или сервер перегружен
popup_blocked, popup_closedокно заблокировано браузером или закрыто до подтверждения
login_in_progressвход уже идёт
not_initializedopen() без init()
invalid_request, invalid_scopeневерные параметры запроса. Если origin страницы не зарегистрирован или вход для бота выключен, окно показывает страницу ошибки, а callback получит popup_closed, когда пользователь его закроет

Как проходит вход во всплывающем окне

  1. SDK открывает окно 550×650 с /auth?client_id=…&redirect_uri=<origin+путь страницы>&response_type=post_message&scope=…. Origin страницы должен быть зарегистрирован командой add origin; регистрировать redirect для этого режима не нужно.
  2. Окно показывает страницу входа: кнопку «Открыть StaticGram» (ссылка sg://oauth?token=…), вход по номеру телефона и QR-код (см. Как пользователь входит).
  3. Пользователь подтверждает вход в приложении или кнопкой «Подтвердить» в сообщении от StaticGram.
  4. Окно передаёт результат странице через postMessage строго на зарегистрированный origin и закрывается. Если браузер потерял связь с окном (мобильные браузеры), страница сама опрашивает /auth/status; ответ доступен только этому origin.

Если страница с SDK открыта как Mini App внутри StaticGram, SDK не открывает окно, а просит подтверждение прямо в приложении. Origin Mini App тоже должен быть зарегистрирован как origin.

OpenID Connect (серверный поток)

Стандартный authorization code flow с обязательным PKCE (S256). Все параметры берутся из discovery, поэтому подойдёт любая OIDC-библиотека, умеющая PKCE: укажите issuer https://oauth.staticgram.top, Client ID, Client Secret и redirect URI, зарегистрированный командой add redirect. В примерах ниже Client ID и Client Secret берутся из переменных окружения STATICGRAM_CLIENT_ID и STATICGRAM_CLIENT_SECRET.

GET /.well-known/openid-configuration
{
  "issuer": "https://oauth.staticgram.top",
  "authorization_endpoint": "https://oauth.staticgram.top/auth",
  "token_endpoint": "https://oauth.staticgram.top/token",
  "jwks_uri": "https://oauth.staticgram.top/.well-known/jwks.json",
  "scopes_supported": ["openid", "profile", "phone", "staticgram:bot_access"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256", "ES256", "EdDSA"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "claims_supported": ["iss", "aud", "sub", "iat", "exp", "nonce", "id", "name", "given_name",
    "family_name", "preferred_username", "picture", "phone_number", "phone_number_verified"],
  "code_challenge_methods_supported": ["S256"],
  "introspection_endpoint": "https://oauth.staticgram.top/introspect",
  "introspection_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"]
}

userinfo_endpoint нет: все данные пользователя приходят в id_token. Refresh-токенов нет.

Scopes

ScopeЧто даёт
openidОбязателен. sub (id пользователя) и служебные claims.
profileid, name, given_name, family_name, preferred_username, picture.
phonephone_number и phone_number_verified, если пользователь согласился поделиться номером на экране подтверждения. Если не согласился, вход всё равно проходит, но без этих claims.
staticgram:bot_accessПросьба разрешить боту писать пользователю. Пользователь может снять галочку; claim об этом не выдаётся, проверяйте результатом отправки сообщения ботом. В запросе можно писать write.

В scope от 1 до 4 значений без повторов. Если бот подписывает токены EdDSA, допустим только openid.

1. Запрос авторизации

Сгенерируйте state, nonce и code_verifier (43-128 символов A-Z a-z 0-9 - . _ ~), сохраните их в сессии и отправьте пользователя на:

Text
https://oauth.staticgram.top/auth?client_id=1780244143
  &redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback
  &response_type=code
  &scope=openid%20profile%20phone
  &state=af0ifjsldkj
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
ПараметрОписание
client_idОбязательно. Client ID.
redirect_uriОбязательно. Должен совпасть с зарегистрированным redirect после нормализации.
response_typeОбязательно, code.
scopeОбязательно, через пробел, с openid.
code_challenge, code_challenge_methodОбязательно. BASE64URL(SHA256(code_verifier)) без =; метод только S256.
stateРекомендуется (защита от CSRF), до 2048 символов. Возвращается без изменений.
nonceРекомендуется, до 1024 символов. Попадает в claim nonce.

Каждый параметр передаётся не больше одного раза. Пользователь видит страницу «Вход на example.com» (см. Как пользователь входит). Запрос действует 5 минут. После подтверждения страница перенаправит браузер на:

Text
https://example.com/auth/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

При отказе или ошибке вместо code придёт error (и state): access_denied (пользователь отклонил), temporarily_unavailable (запрос истёк), invalid_request, invalid_scope, unsupported_response_type, server_error. Если неверны сами client_id или redirect_uri, редиректа не будет: сервер покажет страницу с ошибкой (HTTP 400), чтобы не стать открытым редиректом.

2. Обмен кода на токены

Код одноразовый и живёт 2 минуты. Обменяйте его с сервера запросом application/x-www-form-urlencoded. Клиент аутентифицируется одним способом: заголовком Authorization: Basic base64(client_id:client_secret) (client_secret_basic) или полями client_id и client_secret в теле (client_secret_post); оба сразу нельзя.

Shell
curl -s https://oauth.staticgram.top/token \
  -u "$STATICGRAM_CLIENT_ID:$STATICGRAM_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://example.com/auth/callback \
  -d code_verifier="$CODE_VERIFIER"
Ответ
{
  "access_token": "q0v1…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…"
}

access_token выдаётся для совместимости с библиотеками, но ни к одному API не подходит: используйте id_token. Ошибки: 401 invalid_client (неверный Client ID/Secret или вход выключен), 400 invalid_grant (код неверный, истёк, уже использован, не совпали redirect_uri или PKCE), 400 unsupported_grant_type, 400 invalid_request. Лимит: 60 запросов в минуту на IP и на клиента.

3. Проверка id_token

id_token это JWT. Перед тем как доверять данным, проверьте:

  • подпись ключом из JWKS (https://oauth.staticgram.top/.well-known/jwks.json) по kid из заголовка; алгоритм (RS256, ES256 или EdDSA) задан в @BotFather для бота, принимайте только его. JWKS кэшируется на 5 минут; при неизвестном kid перечитайте набор ключей;
  • iss равен https://oauth.staticgram.top;
  • aud содержит ваш Client ID (в токене это массив из одного элемента);
  • exp не прошёл (токен живёт 1 час), iat разумный;
  • nonce совпадает с отправленным.
ClaimScopeОписание
iss, aud, iat, expopenidстандартные
subopenidid пользователя строкой, например "1780244143"
nonceopenidесли был передан
sidopenidидентификатор этого входа (сессии) для /introspect
idprofileid пользователя числом
nameprofileимя и фамилия
given_nameprofileимя
family_nameprofileфамилия, если указана
preferred_usernameprofileusername без @, если есть
pictureprofileссылка на аватар, если у пользователя есть фото и username
phone_numberphoneномер в международном формате без +, только цифры, например "79991234567"
phone_number_verifiedphoneвсегда true, если номер передан

Данные профиля фиксируются в момент подтверждения. Связывайте аккаунт по sub, а не по username или телефону.

Python (PyJWT)
import os
import jwt  # pip install "pyjwt[crypto]"

STATICGRAM_ISSUER = "https://oauth.staticgram.top"
STATICGRAM_CLIENT_ID = os.environ["STATICGRAM_CLIENT_ID"]  # id бота
jwks = jwt.PyJWKClient(STATICGRAM_ISSUER + "/.well-known/jwks.json")

def verify_staticgram_id_token(id_token: str, nonce: str | None = None) -> dict:
    key = jwks.get_signing_key_from_jwt(id_token)
    claims = jwt.decode(id_token, key, algorithms=["RS256"],  # алгоритм вашего бота
                        audience=STATICGRAM_CLIENT_ID, issuer=STATICGRAM_ISSUER,
                        options={"require": ["exp", "iat", "sub"]})
    if nonce is not None and claims.get("nonce") != nonce:
        raise ValueError("nonce mismatch")
    return claims
Node.js (jose)
import { createRemoteJWKSet, jwtVerify } from "jose";

const STATICGRAM_ISSUER = "https://oauth.staticgram.top";
const JWKS = createRemoteJWKSet(new URL(STATICGRAM_ISSUER + "/.well-known/jwks.json"));

export async function verifyStaticGramIdToken(idToken, nonce) {
  const { payload } = await jwtVerify(idToken, JWKS, {
    issuer: STATICGRAM_ISSUER,
    audience: process.env.STATICGRAM_CLIENT_ID, // id бота
    algorithms: ["RS256"], // алгоритм вашего бота
  });
  if (nonce !== undefined && payload.nonce !== nonce) throw new Error("nonce mismatch");
  return payload;
}
Go (go-oidc)
import (
	"os"

	"github.com/coreos/go-oidc/v3/oidc"
)

provider, err := oidc.NewProvider(ctx, "https://oauth.staticgram.top")
if err != nil {
	return err
}
verifier := provider.Verifier(&oidc.Config{ClientID: os.Getenv("STATICGRAM_CLIENT_ID")})
token, err := verifier.Verify(ctx, rawIDToken) // подпись, iss, aud, exp
if err != nil {
	return err
}
var claims struct {
	Sub      string `json:"sub"`
	Name     string `json:"name"`
	Username string `json:"preferred_username"`
	Nonce    string `json:"nonce"`
}
err = token.Claims(&claims)

Проверка активности входа: /introspect

Пользователь может в любой момент завершить вход на сайте в приложении (Настройки → Устройства). Чтобы узнать об этом, отправьте полученный id_token на /introspect с теми же способами аутентификации, что у /token (Client Secret обязателен):

Shell
curl -s https://oauth.staticgram.top/introspect \
  -u "$STATICGRAM_CLIENT_ID:$STATICGRAM_CLIENT_SECRET" \
  -d token="$ID_TOKEN"
Ответ
{
  "active": true,
  "authorization_active": true,
  "client_id": "1780244143",
  "sub": "1780244143",
  "iss": "https://oauth.staticgram.top",
  "token_type": "id_token",
  "sid": "pQ0uVY4a8l2wO1dCkJ3XxA",
  "iat": 1760000000,
  "exp": 1760003600
}
  • authorization_active: вход (по sid) ещё не отозван пользователем. Остаётся осмысленным и после истечения токена, поэтому по нему удобно продлевать или завершать сессию сайта.
  • active: authorization_active и токен не истёк (как в RFC 7662).
  • Для чужого, повреждённого или подделанного токена ответ {"active": false} без остальных полей. Неверный Client Secret даёт 401 invalid_client.

Работает для токенов из любого способа входа (виджет, JS SDK, OIDC). Лимит: 120 запросов в минуту на IP и 600 на клиента; проверяйте периодически (например, раз в несколько минут на активную сессию), а не на каждый запрос.

Кнопки login_url в боте

Бот может отправить inline-кнопку с LoginUrl: по нажатию пользователь подтверждает вход в приложении и открывает сайт уже авторизованным. На адрес из кнопки добавляются классические поля id, first_name, last_name, username, photo_url, auth_date, hash; проверка такая же, как для виджета, токеном бота из кнопки.

reply_markup
{"inline_keyboard": [[{"text": "Войти на сайт",
  "login_url": {"url": "https://example.com/login", "request_write_access": true}}]]}
  • Origin адреса должен быть зарегистрирован у бота (add origin), а вход включён; иначе отправка сообщения вернёт BUTTON_URL_INVALID или BUTTON_INVALID.
  • bot_username позволяет авторизовать через другого бота; тогда origin регистрируется у него, и подпись делается его токеном.
  • Если у пользователя уже есть неотозванный вход на этот домен через этого бота с теми же правами, повторное нажатие пускает без подтверждения.

Нативные приложения

Для iOS и Android используется тот же authorization code + PKCE, но без Client Secret (публичный клиент, token_endpoint_auth_method=none). Готовых SDK нет, протокол простой:

  1. Зарегистрируйте приложение в /setlogin: add ios <bundle_id> <team_id> <callback> <название> или add android <package> <sha256> <callback> <название>. callback: точная HTTPS-ссылка (universal/app link) или своя схема вида exampleapp://host, без query и фрагмента; служебные схемы самого мессенджера запрещены.
  2. Запросите ссылку: GET https://oauth.staticgram.top/crossapp?client_id=…&redirect_uri=<callback>&response_type=code&scope=openid%20profile&state=…&nonce=…&code_challenge=…&code_challenge_method=S256&ios_sdk=1 (для Android android_sdk=1). Ответ: {"url": "sg://oauth?token=…"}. openid добавляется автоматически.
  3. Откройте эту ссылку: запустится StaticGram, пользователь подтвердит вход, и приложение StaticGram откроет <callback>?code=…&state=….
  4. Обменяйте код на /token с client_id в теле, без client_secret, с тем же redirect_uri и code_verifier. Проверьте id_token как обычно.

Название приложения из регистрации показывается пользователю вместо домена только для ботов с галочкой верификации; для остальных показываются бот и идентификатор приложения.

Рекомендации по безопасности

  • Проверяйте hash или подпись id_token только на сервере. data.user из JS SDK и параметры в адресе не доказывают ничего, пока подпись не проверена.
  • Храните токен бота и Client Secret только на сервере (например, в STATICGRAM_BOT_TOKEN и STATICGRAM_CLIENT_SECRET). При утечке секрета выполните /resetloginsecret, при утечке токена бота /revoke.
  • Проверяйте auth_date (классический формат) и exp, aud, iss, nonce (OIDC). Принимайте только алгоритм, выбранный для бота.
  • В серверном потоке всегда передавайте и сверяйте state, храните code_verifier в сессии пользователя.
  • Регистрируйте только нужные origin и точные redirect URI; удаляйте неиспользуемые. Ответы окна входа и /auth/status отдаются только зарегистрированному origin.
  • Периодически проверяйте /introspect и завершайте сессию сайта, если пользователь отозвал вход.
  • Не встраивайте страницу входа во фрейм: она запрещает это (frame-ancestors 'none').

Особенности и совместимость

  • Настройка. Домены регистрируются в /setlogin (add origin / add redirect). Без зарегистрированного origin не работают ни виджет, ни кнопки login_url.
  • Виджет рисует собственную кнопку, а не iframe; нет data-userpic, телефон через виджет не запрашивается (используйте JS SDK).
  • id_token: алгоритмы RS256 (по умолчанию), ES256, EdDSA; с EdDSA только scope openid. phone_number без знака +. Есть claim sid и эндпоинт /introspect.
  • Нет userinfo_endpoint и refresh-токенов; access_token ни к чему не подходит.
  • Совместимость. Протокол совместим с распространёнными клиентами OpenID Connect; классический формат полей с hash поддерживается для простых сайтов.

Описания методов и типов взяты из официальной документации Telegram Bot API (Bot API 10.3). Адрес API: https://api.staticgram.top