Начало работы

Авторизация

Как получить доступ к API DonateX: персональный external token для своего канала или OAuth 2.0 с PKCE для приложений.

Какой способ выбрать

External token

Свой канал, бот или оверлей

Один бессрочный токен с полным доступом к вашему аккаунту. Без scopes, без refresh — скопировал и работаешь.

OAuth 2.0 + PKCE

Сервис для многих стримеров

Стример входит через DonateX и сам выбирает, какие права выдать. Токены живут час и обновляются через refresh_token.

External token

Откройте кабинет → Настройки → API и доступ и скопируйте токен.
Передавайте его в заголовке Authorization: Bearer.
Если токен утёк — перевыпустите его там же: старый перестанет работать сразу.

Запрос с external token

curl "https://donatex.gg/api/v1/donations?skip=0&take=20" \
  -H "Authorization: Bearer YOUR_EXTERNAL_TOKEN"

Где можно передать токен

Authorizationheader

Bearer <token> — рекомендуемый способ

X-External-Tokenheader

Сам токен без префикса

access_tokenquery

Для SignalR и клиентов, которые не умеют в заголовки. Не используйте в обычных запросах: URL попадает в логи

tokenquery

Устаревший синоним access_token

Не публикуйте токен

External token даёт полный доступ к вашему аккаунту. Не вставляйте его в клиентский код сайта и в публичные репозитории. Для браузерных приложений используйте OAuth с PKCE.

OAuth 2.0 + PKCE

Authorization Code flow с обязательным PKCE. Приложение регистрируется в кабинете — там же выдаются client_id и, для серверных приложений, client_secret.

Сгенерируйте code_verifier и code_challenge.
Перенаправьте пользователя на /api/connect/authorize — он войдёт и подтвердит права.
DonateX вернёт его на ваш redirect_uri с параметром code.
Обменяйте code на токены через /api/connect/token.

1. PKCE

code_verifier храните до конца авторизации и никому не передавайте, в URL уходит только code_challenge.

pkce.js

// Браузер или Node.js 18+
const toBase64Url = (bytes) =>
  btoa(String.fromCharCode(...new Uint8Array(bytes)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

export async function createPkce() {
  const codeVerifier = toBase64Url(crypto.getRandomValues(new Uint8Array(48)));
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier));
  return { codeVerifier, codeChallenge: toBase64Url(digest) };
}

2. Авторизация пользователя

GET /api/connect/authorize

https://donatex.gg/api/connect/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
  &response_type=code
  &scope=openid%20offline_access%20donations.read%20donations.write
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE

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

ID приложения

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

Адрес возврата, точно как в настройках приложения

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

Всегда code

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

Права через пробел, например openid offline_access donations.read

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

Base64Url(SHA-256(code_verifier))

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

Всегда S256

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

Случайная строка для защиты от CSRF — сверьте её в колбэке

3. Обмен кода на токен

Запрос application/x-www-form-urlencoded. Публичные клиенты (SPA, мобильные приложения) не передаютclient_secret — им хватает code_verifier.

POST /api/connect/token

curl -X POST "https://donatex.gg/api/connect/token" \
  -d "grant_type=authorization_code" \
  -d "code=CODE_FROM_CALLBACK" \
  -d "redirect_uri=https://your.app/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=ORIGINAL_CODE_VERIFIER"

Ответ

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid offline_access donations.read donations.write",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

4. Обновление и отзыв

access_token живёт час. Чтобы получить refresh_token, запросите scope offline_access. Каждый refresh возвращает новую пару токенов — сохраняйте обе.

Обновление токена

curl -X POST "https://donatex.gg/api/connect/token" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Отзыв токена при выходе пользователя

curl -X POST "https://donatex.gg/api/connect/revoke" \
  -d "token=REFRESH_OR_ACCESS_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Что нового

Дальше

Scopes