Blyk

Разработчикам

Документация Bot API и входа через Blyk (OAuth 2.0).

Войти через Blyk — OAuth 2.0Версия 1.0.0

OAuth 2.0

«Войти через Blyk» для вашего сайта или приложения: код авторизации, PKCE и токены доступа.

  1. Зарегистрируйте приложение
  2. Отправьте пользователя на /authorize
  3. Обменяйте код на токен
Базовый адресhttps://gateway.blyk.chat

«Войти через Blyk» — сервер авторизации OAuth 2.0 (RFC 6749). Ваш сайт или приложение отправляет человека на страницу Blyk, человек входит и разрешает доступ, а вы получаете токен и по нему — профиль: id, имя, тег и фото. Пароль от Blyk вашему приложению не достаётся никогда.

Что поддерживается

  • Authorization Code (RFC 6749 §4.1) с PKCE (RFC 7636, только S256) и обновление по refresh-токену (§6). Других потоков нет: ни implicit, ни password, ни client credentials, ни device flow.
  • Метаданные сервера — RFC 8414 (/.well-known/oauth-authorization-server).
  • Отзыв токенов — RFC 7009 (/oauth/revoke).
  • Профиль — /oauth/userinfo по Bearer-токену (RFC 6750).
  • Параметр iss в ответе авторизации — RFC 9207.
  • OpenID Connect не поддерживается: нет id_token, нет /.well-known/openid-configuration, нет JWKS и права openid. Токены — непрозрачные строки, а не JWT: проверять их подпись нечем и незачем, кто владелец токена — спрашивайте у /oauth/userinfo.
  • Нет и эндпоинта интроспекции (RFC 7662), и динамической регистрации клиентов (RFC 7591): приложения заводятся только вручную, в приложении Blyk.

Адреса

что адрес
издатель (issuer) https://gateway.blyk.chat
вход и согласие GET https://app.blyk.chat/oauth/authorize
токены POST https://gateway.blyk.chat/oauth/token
отзыв POST https://gateway.blyk.chat/oauth/revoke
профиль GET https://gateway.blyk.chat/oauth/userinfo
метаданные GET https://gateway.blyk.chat/.well-known/oauth-authorization-server

Страница входа живёт в веб-приложении (app.blyk.chat), всё остальное — на шлюзе (gateway.blyk.chat). Тестовый стенд — те же пути на test-app.blyk.chat и test-gateway.blyk.chat; приложения и аккаунты у стендов свои.

Регистрация приложения

Приложения заводятся только в веб-версии Blyk (app.blyk.chat): в мобильных приложениях этих экранов нет.

  1. Откройте вкладку «Вы» → «Разработка» → «Мои приложения» и нажмите «Создать приложение».
  2. Заполните, «как его увидят»: название (1–64 знака), описание (необязательно, до 500 знаков), сайт (https://…) и значок. Название, значок и сайт человек увидит на экране «Войти через Blyk».
  3. Добавьте адреса возврата — от 1 до 10, каждый до 512 знаков. Сравниваются они посимвольно, поэтому указывайте ровно тот адрес, который будете передавать в redirect_uri:
    • https:// — любой;
    • http:// — только на свой компьютер: localhost, 127.0.0.1, [::1] (для разработки и настольных приложений). Порт — тоже часть адреса: http://localhost:3000/cb и http://localhost:5173/cb — разные адреса, зарегистрируйте нужные;
    • своя схема мобильного приложения — только с точкой в имени, например com.example.app:/oauth/cb (RFC 8252 §7.1);
    • без #фрагмента; javascript:, data:, file: и подобные запрещены.
  4. Выберите тип клиента — потом его не поменять:
    • Конфиденциальный — для сайта со своим сервером: код обменивается на токен с секретом, PKCE — по желанию (но мы советуем его всегда).
    • Публичный — для SPA и мобильных приложений, где секрет не спрятать: секрета нет, PKCE (S256) обязателен.
  5. Нажмите «Сохранить». В разделе «Ключи» появятся client_id (вида blyk_ + 24 hex-знака) и — у конфиденциального клиента — client_secret (blyk_cs_…). Секрет показывается один раз, показать его снова нельзя. Потеряли — «Сгенерировать новый секрет»: старый перестанет работать сразу.

У одного аккаунта — до 20 приложений. Удаление приложения необратимо: вход перестаёт работать у всех, выданные токены гаснут сразу.

Поток входа по шагам

  1. Сгенерируйте случайные state (защита от CSRF) и code_verifier (PKCE), посчитайте code_challenge и сохраните state и code_verifier у себя — в сессии сервера или в sessionStorage.
  2. Отправьте браузер на https://app.blyk.chat/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=profile&state=…&code_challenge=…&code_challenge_method=S256.
  3. Человек входит в Blyk (если ещё не вошёл), выбирает аккаунт и видит экран согласия: название и значок вашего приложения и список прав. Если этот аккаунт уже давал вашему приложению те же права, экран согласия не показывается — Blyk сразу возвращает человека к вам.
  4. Blyk возвращает браузер на redirect_uri: ?code=blyk_ac_…&state=…&iss=https://gateway.blyk.chat — или ?error=access_denied&state=…&iss=…, если человек нажал «Отмена».
  5. Проверьте state (совпадает с сохранённым) и iss (равен https://gateway.blyk.chat). Не совпало — прервите вход.
  6. Обменяйте код на токены: POST /oauth/token с grant_type=authorization_code, code, тем же redirect_uri и code_verifier. У кода 60 секунд и одна попытка.
  7. Узнайте, кто вошёл: GET /oauth/userinfo с Authorization: Bearer <access_token>. Привязывайте аккаунт к полю sub — оно постоянно; имя и тег человек может сменить.
  8. Обновляйте access-токен по refresh_token, когда он истекает (через час), — POST /oauth/token с grant_type=refresh_token. Каждый раз сохраняйте новый refresh-токен.
  9. При выходе отзовите refresh-токен: POST /oauth/revoke.

Когда человек впервые разрешает вашему приложению вход (или даёт новые права), Blyk пишет ему об этом в служебный чат — со ссылкой на «Подключённые приложения», где доступ можно отозвать.

PKCE

PKCE (RFC 7636) не даёт воспользоваться перехваченным кодом: обменять код может только тот, кто знает code_verifier, а в адресе ходит лишь его хеш — code_challenge.

  • code_verifier — 43–128 знаков из A–Z a–z 0–9 - . _ ~, криптостойко случайный.
  • code_challenge = BASE64URL(SHA256(code_verifier)) без = — от сырых 32 байт хеша, ровно 43 знака. Не hex-строка и не base64 от hex.
  • code_challenge_method — только S256. plain не принимается ни от кого.
  • Публичному клиенту PKCE обязателен, конфиденциальному — по желанию. Но если code_challenge был в запросе авторизации, code_verifier обязан быть при обмене; и наоборот — code_verifier без code_challenge отвергается (invalid_grant).
// Браузер или Node 18+: Web Crypto.
function base64url(bytes) {
  let s = '';
  for (const b of new Uint8Array(bytes)) s += String.fromCharCode(b);
  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

// 32 случайных байта → 43 знака base64url.
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(
  await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)),
);
const state = base64url(crypto.getRandomValues(new Uint8Array(16)));

То же в shell:

VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')

Права (scope)

право что даёт
profile id, имя, тег и фото профиля (/oauth/userinfo). Чаты, контакты и почта остаются закрыты.

Сейчас право одно. scope — список через пробел; не передан или пуст — profile. Неизвестное право — invalid_scope. Согласие запоминается объединением: разрешив однажды больше, человек не увидит экран согласия, когда попросят меньше.

Сроки и пределы

что значение
код авторизации 60 секунд, одноразовый
access-токен 1 час (expires_in: 3600)
refresh-токен 30 дней с момента выдачи; каждое обновление выдаёт новый на те же 30 дней
picture в профиле подписанная ссылка, живёт сутки
метаданные кешируются на 5 минут (Cache-Control: public, max-age=300)
тело запроса к /oauth/token, /oauth/revoke до 16 КБ
state до 1024 знаков
приложений на аккаунт 20
адресов возврата у приложения 1–10, каждый до 512 знаков

Префиксы делают токены Blyk узнаваемыми в журналах и для сканеров утечек: blyk_ac_ — код, blyk_at_ — access, blyk_rt_ — refresh, blyk_cs_ — секрет клиента. Длину и устройство остальной части не закладывайте в код.

Ротация refresh-токенов и защита от повторов

  • Каждое обновление гасит предъявленный refresh-токен и выдаёт новую пару.
  • Предъявить уже использованный refresh-токен — признак кражи: Blyk отвечает invalid_grant и отзывает всю цепочку — все access- и refresh-токены, выданные по этому входу, включая самые свежие. Человеку придётся войти заново.
  • Два одновременных обновления одним refresh-токеном выглядят так же, как повтор: одно пройдёт, второе погасит цепочку. Обновляйте токен строго по одному (очередь или блокировка на пользователя).
  • Код авторизации, предъявленный второй раз, тоже отзывает всё, что по нему уже выдано.

Токены перестают работать и тогда, когда человек отключил ваше приложение («Разработка» → «Подключённые приложения»), удалил аккаунт или был заблокирован, а также при удалении приложения.

Безопасность

  • Всегда передавайте и проверяйте state; проверяйте iss в ответе авторизации.
  • Используйте PKCE и в конфиденциальном клиенте.
  • Секрет клиента — только на сервере. Не кладите его в SPA, мобильное приложение или репозиторий; утёк — сгенерируйте новый.
  • Храните токены как пароли: на сервере, в зашифрованном хранилище или в защищённом хранилище ОС. Ответы с токенами приходят с Cache-Control: no-store.
  • Страницу входа нельзя открыть внутри <iframe> (защита от clickjacking): используйте переход на всю страницу или всплывающее окно.
  • /oauth/token, /oauth/revoke, /oauth/userinfo и метаданные отвечают с Access-Control-Allow-Origin: * и не читают куки: публичный клиент может обменивать код прямо из браузера.
  • Access-токен в адресе (?access_token=) не принимается — только в заголовке Authorization или в теле POST.

Ошибки

Ошибки — по RFC 6749 §5.2 и RFC 6750 §3: JSON {"error": "<код>"}. Поля error_description нет: код и HTTP-статус — всё, что говорит сервер. На /oauth/authorize ошибка приходит параметрами адреса возврата.

код HTTP когда
invalid_request 400 нет обязательного параметра, параметр передан дважды, секрет и в Authorization, и в теле, не тот HTTP-метод (тогда 405); на /authorize — нет response_type, нет PKCE у публичного клиента, метод не S256, code_challenge не 43 знака base64url, state длиннее 1024
invalid_client 401 неизвестный client_id, неверный или отсутствующий секрет у конфиденциального клиента, секрет у публичного
invalid_grant 400 код или refresh-токен неизвестен, истёк, уже использован или выдан другому клиенту; redirect_uri или code_verifier не те; приложение отключено; аккаунт удалён или заблокирован
unsupported_grant_type 400 grant_type не authorization_code и не refresh_token
invalid_scope 400 неизвестное право; при обновлении — право шире выданного
unsupported_response_type — /authorize: response_type не code
access_denied — /authorize: человек нажал «Отмена»
invalid_token 401 /userinfo: токена нет, он истёк, отозван или неизвестен
server_error 500 сбой у Blyk
temporarily_unavailable 503 служба авторизации не ответила вовремя — повторите позже

Если client_id неизвестен или redirect_uri не зарегистрирован, Blyk не возвращает человека к вам (адрес не подтверждён) — ошибка показывается на странице входа.

Методы

Авторизация

Вход и согласие человека в браузере. Страница — в веб-приложении (app.blyk.chat), а не на шлюзе.

get/oauth/authorize

Вход и согласие

Не вызывается из кода: сюда переходит браузер человека — полной страницей или во всплывающем окне (не в <iframe>: там страница не откроется).

Страница при необходимости просит войти в Blyk, даёт выбрать аккаунт и показывает экран согласия. Решение возвращается переходом браузера на redirect_uri (см. обратный вызов authorizationResponse):

  • «Разрешить» — code, state, iss;
  • «Отмена» — error=access_denied, state, iss;
  • неверный запрос — error=<код>, state, iss.

Свои параметры адреса возврата (…/cb?tenant=1) сохраняются, параметры Blyk добавляются к ним.

Неизвестный client_id и незарегистрированный redirect_uri на ваш адрес не уводят: ошибка остаётся на странице Blyk («Войти не получится»).

Если этот аккаунт уже давал вашему приложению запрошенные права, экран согласия пропускается и браузер сразу возвращается с code. Параметра prompt (принудительно спросить ещё раз) нет.

Параметры

response_typestringобязательныйв строке запроса

Только code. Другое значение — unsupported_response_type, нет параметра — invalid_request.

code
client_idstringобязательныйв строке запроса

client_id приложения из «Мои приложения». Неизвестный — ошибка на странице Blyk, без перехода к вам.

len 0…64
redirect_uristringнеобязательныйв строке запроса

Один из зарегистрированных адресов возврата, посимвольно. Можно не передавать, только если у приложения адрес ровно один. Не совпал ни с одним — ошибка на странице Blyk, без перехода к вам. Передали здесь — передайте тот же адрес в /oauth/token; не передали — не передавайте и там.

len 0…512
scopestringнеобязательныйв строке запроса

Права через пробел. Не передан или пуст — profile. Неизвестное право — invalid_scope.

= "profile"
statestringнеобязательныйв строке запроса

Случайное значение против CSRF; вернётся без изменений. Формально необязателен, но передавайте всегда. До 1024 знаков, длиннее — invalid_request.

len 0…1024
code_challengestringнеобязательныйв строке запроса

PKCE: BASE64URL(SHA256(code_verifier)) без =, ровно 43 знака. Обязателен публичному клиенту; конфиденциальному — по желанию, но советуем всегда.

len 43…43/^[A-Za-z0-9_-]{43}$/
code_challenge_methodstringнеобязательныйв строке запроса

Только S256. Обязателен вместе с code_challenge; без code_challenge передавать нельзя. plain — invalid_request.

S256

Ответы

200
string

HTML-страница входа и согласия (веб-приложение Blyk). Отдаётся с X-Frame-Options: DENY и Content-Security-Policy: frame-ancestors 'none'. Результат приходит не в этом ответе, а переходом браузера на redirect_uri.

Запрос
curl 'https://app.blyk.chat/oauth/authorize?response_type=code&client_id=blyk_3f9a1c0e7b2d4a6c8e0f1a2b&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=profile&state=4kq0vZb3Yt8sQm1xWc7pLg&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256'
Ответ
<!doctype html><html lang="ru">…</html>
Методы

Токены

Обмен кода на токены, обновление и отзыв.

post/oauth/token

Получить или обновить токены

Два вида запроса — по grant_type:

  • authorization_code — обмен кода из адреса возврата на пару токенов;
  • refresh_token — новая пара по refresh-токену. Предъявленный refresh-токен гаснет; повторное его предъявление отзывает всю цепочку.

Тело — application/x-www-form-urlencoded, не JSON. Каждый параметр — не больше одного раза.

Как представиться:

клиент способ (token_endpoint_auth_method)
конфиденциальный Authorization: Basic base64(client_id:client_secret) (client_secret_basic; client_id и секрет предварительно form-кодируются, RFC 6749 §2.3.1) или client_id + client_secret в теле (client_secret_post)
публичный только client_id в теле (none); секрет передавать нельзя — invalid_client

Оба способа сразу (Basic и client_secret в теле) — invalid_request.

# Конфиденциальный клиент: код → токены
curl -u "$CLIENT_ID:$CLIENT_SECRET" https://gateway.blyk.chat/oauth/token \
  -d grant_type=authorization_code -d code="$CODE" \
  -d redirect_uri=https://example.com/oauth/callback \
  -d code_verifier="$VERIFIER"

# Публичный клиент: обновление
curl https://gateway.blyk.chat/oauth/token \
  -d grant_type=refresh_token -d refresh_token="$REFRESH" \
  -d client_id="$CLIENT_ID"

Тело запроса application/x-www-form-urlencoded AuthorizationCodeTokenRequest | RefreshTokenRequest

Параметры запроса токена. Набор полей зависит от grant_type.

Ответы

200
TokenResponse

Новая пара токенов.

400
OAuthError

Отказ протокола: invalid_request, invalid_grant, unsupported_grant_type или invalid_scope.

401
OAuthError

invalid_client: неизвестный client_id, неверный или отсутствующий секрет у конфиденциального клиента, секрет у публичного. Если клиент представлялся через Authorization: Basic, в ответе — WWW-Authenticate: Basic realm="blyk".

405
OAuthError

Не тот HTTP-метод. Заголовок Allow перечисляет допустимые.

500
OAuthError

Сбой у Blyk. Запрос можно повторить.

503
OAuthError

Служба авторизации недоступна или не ответила за 10 секунд. Повторите позже.

Запрос
curl -X POST 'https://gateway.blyk.chat/oauth/token' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=blyk_ac_q2V3n8Jw0XoT5bLr1cYh7uPz4kDf9sGe6aMi2NtR0vE' \
  --data-urlencode 'redirect_uri=https://example.com/oauth/callback' \
  --data-urlencode 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \
  --data-urlencode 'client_id=blyk_3f9a1c0e7b2d4a6c8e0f1a2b'
Ответ
{
  "access_token": "blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "scope": "profile"
}
post/oauth/revoke

Отозвать токен

Отзыв по RFC 7009. Клиент представляется так же, как в /oauth/token.

  • Отзыв refresh-токена гасит всю цепочку: его самого и все access-токены, выданные по этому входу.
  • Отзыв access-токена гасит только его.
  • Неизвестный, чужой (выданный другому клиенту) или уже отозванный токен — тоже 200: ответ не подсказывает, существует ли токен.

Согласие человека при этом остаётся: при следующем входе экран согласия не покажется. Полностью отключить приложение может только сам человек — в «Подключённых приложениях».

curl -u "$CLIENT_ID:$CLIENT_SECRET" https://gateway.blyk.chat/oauth/revoke \
  -d token="$REFRESH" -d token_type_hint=refresh_token

Тело запроса application/x-www-form-urlencoded RevokeRequest

Токен для отзыва.

tokenstringобязательный

Access- или refresh-токен этого клиента.

token_type_hintstringнеобязательный

Подсказка о виде токена. Принимается, но не нужна — вид Blyk определяет сам.

access_tokenrefresh_token
client_idstringнеобязательный

client_id. Обязателен, если клиент не представляется через Authorization: Basic.

client_secretstringнеобязательный

Секрет конфиденциального клиента (client_secret_post).

Ответы

200

Готово (или токена и так не было). Тела нет.

400
OAuthError

invalid_request: нет token, параметр передан дважды или клиент представился двумя способами сразу.

401
OAuthError

invalid_client: неизвестный client_id, неверный или отсутствующий секрет у конфиденциального клиента, секрет у публичного. Если клиент представлялся через Authorization: Basic, в ответе — WWW-Authenticate: Basic realm="blyk".

405
OAuthError

Не тот HTTP-метод. Заголовок Allow перечисляет допустимые.

500
OAuthError

Сбой у Blyk. Запрос можно повторить.

503
OAuthError

Служба авторизации недоступна или не ответила за 10 секунд. Повторите позже.

Запрос
curl -X POST 'https://gateway.blyk.chat/oauth/revoke' \
  --data-urlencode 'token=blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr' \
  --data-urlencode 'token_type_hint=refresh_token'
Ответ
// Готово (или токена и так не было). Тела нет.
Методы

Пользователь

Профиль человека, вошедшего через Blyk.

get/oauth/userinfo

Профиль вошедшего

Кто владелец access-токена. Токен — в заголовке Authorization: Bearer …. В адресе (?access_token=) он не принимается.

Поля по правам:

право поля
всегда sub, id
profile name, display_name, username, preferred_username, picture, avatar_url

Поля без значения не приходят вовсе: нет тега — нет username и preferred_username, нет фото — нет picture и avatar_url.

Это не OpenID Connect UserInfo, хотя имена sub, name, preferred_username и picture совпадают: id_token нет, и email Blyk не отдаёт.

curl -H "Authorization: Bearer $ACCESS" https://gateway.blyk.chat/oauth/userinfo

Ответы

200
UserInfo

Профиль. Набор полей зависит от прав токена.

401
OAuthError

invalid_token: токена нет, он истёк, отозван, неизвестен, или аккаунт удалён либо заблокирован. Получите новый по refresh-токену или попросите человека войти заново.

405
OAuthError

Не тот HTTP-метод. Заголовок Allow перечисляет допустимые.

500
OAuthError

Сбой у Blyk. Запрос можно повторить.

503
OAuthError

Служба авторизации недоступна или не ответила за 10 секунд. Повторите позже.

Запрос
curl 'https://gateway.blyk.chat/oauth/userinfo'
Ответ
{
  "sub": "7349016627290100000",
  "id": "7349016627290100000",
  "name": "Алекс",
  "display_name": "Алекс",
  "username": "alex",
  "preferred_username": "alex",
  "picture": "https://files.blyk.chat/s/av_7Kq2…?vt=…",
  "avatar_url": "https://files.blyk.chat/s/av_7Kq2…?vt=…"
}
post/oauth/userinfo

Профиль вошедшего (POST)

То же, что GET. Токен — в заголовке Authorization: Bearer … или полем access_token в теле application/x-www-form-urlencoded (RFC 6750 §2.2). Заголовок, если есть, важнее тела.

Тело запроса application/x-www-form-urlencoded UserInfoFormRequest

Нужно, только если токен не в заголовке.

access_tokenstringнеобязательный

Access-токен — если не передан в заголовке Authorization.

Ответы

200
UserInfo

Профиль. Набор полей зависит от прав токена.

401
OAuthError

invalid_token: токена нет, он истёк, отозван, неизвестен, или аккаунт удалён либо заблокирован. Получите новый по refresh-токену или попросите человека войти заново.

500
OAuthError

Сбой у Blyk. Запрос можно повторить.

503
OAuthError

Служба авторизации недоступна или не ответила за 10 секунд. Повторите позже.

Запрос
curl -X POST 'https://gateway.blyk.chat/oauth/userinfo' \
  --data-urlencode 'access_token=blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw'
Ответ
{
  "sub": "7349016627290100000",
  "id": "7349016627290100000",
  "name": "Алекс",
  "display_name": "Алекс",
  "username": "alex",
  "preferred_username": "alex",
  "picture": "https://files.blyk.chat/s/av_7Kq2…?vt=…",
  "avatar_url": "https://files.blyk.chat/s/av_7Kq2…?vt=…"
}
Методы

Служебное

Метаданные сервера авторизации для автоматической настройки клиентов.

get/.well-known/oauth-authorization-server

Метаданные сервера

Документ RFC 8414: адреса и возможности сервера. Библиотеки OAuth умеют настраиваться по нему сами — укажите им издателя https://gateway.blyk.chat.

Поддерживается и HEAD. Ответ кешируется на 5 минут.

/.well-known/openid-configuration и jwks_uri нет: OpenID Connect не поддерживается.

Ответы

200
AuthorizationServerMetadata

Метаданные.

405

Не GET/HEAD. Тела нет.

500
OAuthError

Сбой у Blyk. Запрос можно повторить.

503
OAuthError

Служба авторизации недоступна или не ответила за 10 секунд. Повторите позже.

Запрос
curl 'https://gateway.blyk.chat/.well-known/oauth-authorization-server'
Ответ
{
  "issuer": "https://gateway.blyk.chat",
  "authorization_endpoint": "https://app.blyk.chat/oauth/authorize",
  "token_endpoint": "https://gateway.blyk.chat/oauth/token",
  "revocation_endpoint": "https://gateway.blyk.chat/oauth/revoke",
  "userinfo_endpoint": "https://gateway.blyk.chat/oauth/userinfo",
  "scopes_supported": [
    "profile"
  ],
  "response_types_supported": [
    "code"
  ],
  "response_modes_supported": [
    "query"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "revocation_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "authorization_response_iss_parameter_supported": true
}
Объекты

Объекты

AuthorizationCodeTokenRequest

object

Обмен кода авторизации на токены (RFC 6749 §4.1.3, RFC 7636 §4.5).

grant_typestringобязательный

Вид запроса.

authorization_code
codestringобязательный

Код из адреса возврата. 60 секунд, одноразовый; повторное предъявление отзывает всё, что по нему выдано.

redirect_uristringнеобязательный

Ровно тот же redirect_uri, что был в запросе авторизации. Если там его не было — не передавайте и здесь: любое расхождение, включая лишний параметр, — invalid_grant.

code_verifierstringнеобязательный

PKCE-верификатор. Обязателен, если в авторизации был code_challenge; запрещён, если не было.

len 43…128
client_idstringнеобязательный

client_id. Обязателен, если клиент не представляется через Authorization: Basic (публичный клиент или client_secret_post).

client_secretstringнеобязательный

Секрет конфиденциального клиента (client_secret_post). Нельзя вместе с Basic; публичному клиенту — нельзя вовсе.

{
  "grant_type": "authorization_code",
  "code": "blyk_ac_q2V3n8Jw0XoT5bLr1cYh7uPz4kDf9sGe6aMi2NtR0vE",
  "redirect_uri": "https://example.com/oauth/callback",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "client_id": "blyk_3f9a1c0e7b2d4a6c8e0f1a2b"
}

RefreshTokenRequest

object

Новая пара токенов по refresh-токену (RFC 6749 §6). Предъявленный refresh-токен гаснет; сохраните новый из ответа.

grant_typestringобязательный

Вид запроса.

refresh_token
refresh_tokenstringобязательный

Последний полученный refresh-токен. Уже использованный — invalid_grant и отзыв всей цепочки.

scopestringнеобязательный

Сузить права новой пары. Не передан — те же, что были. Шире выданных — invalid_scope.

client_idstringнеобязательный

client_id. Обязателен, если клиент не представляется через Authorization: Basic.

client_secretstringнеобязательный

Секрет конфиденциального клиента (client_secret_post).

{
  "grant_type": "refresh_token",
  "refresh_token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "client_id": "blyk_3f9a1c0e7b2d4a6c8e0f1a2b"
}

TokenResponse

object

Пара токенов (RFC 6749 §5.1).

access_tokenstringобязательный

Access-токен для /oauth/userinfo. Непрозрачная строка с префиксом blyk_at_.

token_typestringобязательный

Всегда Bearer.

Bearer
expires_inintegerобязательный

Сколько секунд живёт access-токен. Сейчас 3600.

refresh_tokenstringобязательный

Новый refresh-токен (префикс blyk_rt_), живёт 30 дней. Приходит при каждом обмене и обновлении; предыдущий после этого недействителен.

scopestringобязательный

Выданные права через пробел.

{
  "access_token": "blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "scope": "profile"
}

RevokeRequest

object

Запрос отзыва (RFC 7009 §2.1).

tokenstringобязательный

Access- или refresh-токен этого клиента.

token_type_hintstringнеобязательный

Подсказка о виде токена. Принимается, но не нужна — вид Blyk определяет сам.

access_tokenrefresh_token
client_idstringнеобязательный

client_id. Обязателен, если клиент не представляется через Authorization: Basic.

client_secretstringнеобязательный

Секрет конфиденциального клиента (client_secret_post).

{
  "token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "token_type_hint": "refresh_token"
}

UserInfoFormRequest

object

Токен в теле POST (RFC 6750 §2.2).

access_tokenstringнеобязательный

Access-токен — если не передан в заголовке Authorization.

{
  "access_token": "blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw"
}

UserInfo

object

Профиль человека. Пустые поля не приходят. Пары name/display_name, username/preferred_username, picture/avatar_url — одно и то же значение под двумя именами, для библиотек с разными ожиданиями.

substringобязательный

Id пользователя Blyk — строка из цифр (снежинка, в float64 не помещается). Постоянен; к нему и привязывайте аккаунт.

idstringобязательный

То же, что sub.

namestringнеобязательный

Отображаемое имя. Право profile. Человек может его сменить.

display_namestringнеобязательный

То же, что name.

usernamestringнеобязательный

Тег (@alex без @). Право profile. Нет тега — поля нет. Может смениться.

preferred_usernamestringнеобязательный

То же, что username.

picturestring (uri)необязательный

Фото профиля. Право profile. Обычно — подписанная ссылка сервера файлов Blyk, живёт сутки: нужна картинка дольше — скопируйте её к себе. Нет фото — поля нет.

avatar_urlstring (uri)необязательный

То же, что picture.

{
  "sub": "7349016627290100000",
  "id": "7349016627290100000",
  "name": "Алекс",
  "display_name": "Алекс",
  "username": "alex",
  "preferred_username": "alex",
  "picture": "https://files.blyk.chat/s/av_7Kq2…?vt=…",
  "avatar_url": "https://files.blyk.chat/s/av_7Kq2…?vt=…"
}

AuthorizationServerMetadata

object

Метаданные сервера авторизации (RFC 8414 §2).

issuerstring (uri)обязательный

Издатель. Его же возвращает iss в ответе авторизации.

authorization_endpointstring (uri)обязательный

Страница входа и согласия (в веб-приложении, на другом домене).

token_endpointstring (uri)обязательный

Обмен кода и обновление токенов.

revocation_endpointstring (uri)необязательный

Отзыв токенов (RFC 7009).

userinfo_endpointstring (uri)необязательный

Профиль по access-токену.

scopes_supportedstring[]необязательный

Известные права.

response_types_supportedstring[]обязательный

Только code.

response_modes_supportedstring[]необязательный

Ответ авторизации — только параметрами адреса (query).

grant_types_supportedstring[]необязательный

Поддерживаемые grant_type.

code_challenge_methods_supportedstring[]необязательный

Методы PKCE — только S256.

token_endpoint_auth_methods_supportedstring[]необязательный

Способы аутентификации клиента на /oauth/token.

revocation_endpoint_auth_methods_supportedstring[]необязательный

Способы аутентификации клиента на /oauth/revoke.

authorization_response_iss_parameter_supportedbooleanнеобязательный

Ответ авторизации содержит iss (RFC 9207).

service_documentationstring (uri)необязательный

Ссылка на документацию. Приходит, только если задана в настройках сервера.

{
  "issuer": "https://gateway.blyk.chat",
  "authorization_endpoint": "https://app.blyk.chat/oauth/authorize",
  "token_endpoint": "https://gateway.blyk.chat/oauth/token",
  "revocation_endpoint": "https://gateway.blyk.chat/oauth/revoke",
  "userinfo_endpoint": "https://gateway.blyk.chat/oauth/userinfo",
  "scopes_supported": [
    "profile"
  ],
  "response_types_supported": [
    "code"
  ],
  "response_modes_supported": [
    "query"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "revocation_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "authorization_response_iss_parameter_supported": true
}

OAuthError

object

Ошибка протокола (RFC 6749 §5.2, RFC 6750 §3.1). Других полей нет.

errorOAuthErrorCodeобязательный

Код ошибки HTTP-эндпоинтов:

  • invalid_request — нет обязательного параметра, параметр дважды, два способа аутентификации сразу, не тот HTTP-метод;
  • invalid_client — клиент не опознан (401);
  • invalid_grant — код или refresh-токен не годится;
  • unsupported_grant_type — grant_type не поддерживается;
  • invalid_scope — неизвестное право или шире выданного;
  • invalid_token — access-токен не годится (401, /oauth/userinfo);
  • server_error — сбой у Blyk (500);
  • temporarily_unavailable — повторите позже (503).
invalid_requestinvalid_clientinvalid_grantunsupported_grant_typeinvalid_scopeinvalid_tokenserver_errortemporarily_unavailable
{
  "error": "invalid_grant"
}

OAuthErrorCode

string

Код ошибки HTTP-эндпоинтов:

  • invalid_request — нет обязательного параметра, параметр дважды, два способа аутентификации сразу, не тот HTTP-метод;
  • invalid_client — клиент не опознан (401);
  • invalid_grant — код или refresh-токен не годится;
  • unsupported_grant_type — grant_type не поддерживается;
  • invalid_scope — неизвестное право или шире выданного;
  • invalid_token — access-токен не годится (401, /oauth/userinfo);
  • server_error — сбой у Blyk (500);
  • temporarily_unavailable — повторите позже (503).
invalid_requestinvalid_clientinvalid_grantunsupported_grant_typeinvalid_scopeinvalid_tokenserver_errortemporarily_unavailable
"invalid_grant"

AuthorizeErrorCode

string

Код ошибки в адресе возврата (RFC 6749 §4.1.2.1):

  • access_denied — человек нажал «Отмена»;
  • invalid_request — нет response_type, нет PKCE у публичного клиента, метод не S256, code_challenge не 43 знака base64url, code_challenge_method без code_challenge, state длиннее 1024;
  • unsupported_response_type — response_type не code;
  • invalid_scope — неизвестное право.
access_deniedinvalid_requestunsupported_response_typeinvalid_scope
"access_denied"