Хуткі старт
Bototeka працуе з любой бібліятэкай OpenID Connect, якая падтрымлівае Authorization Code і PKCE S256.
Стварыце праграму
Укажыце назву сэрвісу, адрас вяртання і, калі трэба, лагатып. Звароты ад Google, Apple і Yandex апрацоўвае Bototeka.
Захавайце ўліковыя даныя
Скапіруйце Client ID і Client Secret. Сакрэт паказваецца толькі адзін раз.
Наладзьце OIDC
Перадайце бібліятэцы issuer. Астатнія endpoint яна знойдзе аўтаматычна.
Праверце ўваход
Пачніце ўваход, праверце state і nonce, абмяняйце код і стварыце лакальную сесію.
- Issuer
- https://bototeka.com/api
- Discovery URL
- https://bototeka.com/api/.well-known/openid-configuration
- Service API
- https://api.bototeka.com/api/identity/v1
- Прыклад Redirect URI
- https://service.example/auth/callback
Праверка падключэння
Даступна ўладальніку і адміністратару без балансу
Гэты тэст правярае налады Bototeka і даступнасць endpoint правайдара. Інтэрактыўны ўваход карыстальніка правяраецца асобна.
Адкрыць налады OAuthУваход і токены
Ваш сервер стварае PKCE, state і nonce, накіроўвае карыстальніка ў Bototeka і атрымлівае толькі кароткачасовы код аўтарызацыі.
import { createHash, randomBytes } from "node:crypto";
const clientId = process.env.BOTOTEKA_CLIENT_ID;
if (!clientId) throw new Error("BOTOTEKA_CLIENT_ID is required");
const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");
const nonce = randomBytes(24).toString("base64url");
const authorize = new URL("https://bototeka.com/api/oauth/authorize");
authorize.search = new URLSearchParams({
client_id: clientId,
redirect_uri: "https://service.example/auth/callback",
response_type: "code",
scope: "openid email profile",
code_challenge: challenge,
code_challenge_method: "S256",
state,
nonce,
}).toString();
// Save verifier, state and nonce in the user's server-side session.
console.log(authorize.toString());curl --request POST 'https://bototeka.com/api/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'code=CODE_FROM_CALLBACK' \
--data-urlencode 'redirect_uri=https://service.example/auth/callback' \
--data-urlencode 'code_verifier=SAVED_PKCE_VERIFIER'curl 'https://bototeka.com/api/oauth/userinfo' \
--header 'Authorization: Bearer ACCESS_TOKEN'Даныя рэгістрацыі праз API
Стварыце API-ключ у наладах кампаніі і запытвайце кліентаў або падзеі яе праграм.
/applications/{applicationId}/customersВяртае sub, пацверджаны email, імя і час актыўнасці.
/applications/{applicationId}/eventsВяртае рэгістрацыю або ўваход, суму, валюту, статус і час падзеі.
curl 'https://api.bototeka.com/api/identity/v1/applications/APPLICATION_ID/customers?limit=50' \
--header 'Authorization: Bearer btk_v1_YOUR_API_KEY'curl 'https://api.bototeka.com/api/identity/v1/applications/APPLICATION_ID/events?limit=50' \
--header 'Authorization: Bearer btk_v1_YOUR_API_KEY'Для чытання патрэбны identity:read. Перадавайце ключ як Bearer-токен і захоўвайце на серверы.
Вэбхукі
Падпішыцеся на падзеі ў наладах кампаніі. Адрас павінен выкарыстоўваць HTTPS. Сакрэт подпісу паказваецца адзін раз.
identity.registration.completed.v1Рэгістрацыя завершана і запісана ў журнале выкарыстання.
identity.login.completed.v1Паўторны ўваход завершаны і запісаны ў журнале выкарыстання.
Дастаўка адбываецца прынамсі адзін раз. Адсейвайце паўторы па event ID, прымайце падзеі ў любым парадку і вяртайце 2xx толькі пасля захавання.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyBototekaWebhook(rawBody, headers, secret) {
const timestamp = headers["x-bototeka-webhook-timestamp"];
const received = headers["x-bototeka-webhook-signature"];
if (!timestamp || !received) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = "v1=" + createHmac("sha256", secret)
.update(timestamp + "." + rawBody)
.digest("hex");
const left = Buffer.from(expected);
const right = Buffer.from(received);
return left.length === right.length && timingSafeEqual(left, right);
}Праверкі перад запускам
- Выкарыстоўвайце дакладны HTTPS Redirect URI і не прымайце вяртанне на адвольны адрас.
- Для кожнай спробы стварайце новыя state, nonce і PKCE verifier і захоўвайце іх у сервернай сесіі.
- Не захоўвайце Client Secret, API-ключы, access token і refresh token у браўзеры або мабільнай аналітыцы.
- Запытвайце offline_access, толькі калі серверу сапраўды патрэбная працяглая сесія.
- Правярайце подпіс вэбхука па неапрацаваным целе запыту і бяспечна апрацоўвайце паўторную дастаўку.
Памылкі і аднаўленне
invalid_requestШто адбылося
Абавязковы параметр адсутнічае або няправільны.
Што рабіць
Праверце Redirect URI, PKCE, state, nonce і Content-Type.
invalid_grantШто адбылося
Тэрмін кода скончыўся, ён ужо выкарыстаны або не адпавядае verifier.
Што рабіць
Пачніце новы ўваход. Не паўтарайце абмен таго ж кода.
temporarily_unavailableШто адбылося
На балансе праграмы недастаткова сродкаў.
Што рабіць
Папоўніце баланс OAuth і пачніце новы ўваход.
429Што адбылося
Перавышаны ліміт запытаў або спроб пацверджання.
Што рабіць
Выконвайце Retry-After і паўтарайце з выпадковай дадатковай затрымкай.
| Код | Што адбылося | Што рабіць |
|---|---|---|
| invalid_request | Абавязковы параметр адсутнічае або няправільны. | Праверце Redirect URI, PKCE, state, nonce і Content-Type. |
| invalid_grant | Тэрмін кода скончыўся, ён ужо выкарыстаны або не адпавядае verifier. | Пачніце новы ўваход. Не паўтарайце абмен таго ж кода. |
| temporarily_unavailable | На балансе праграмы недастаткова сродкаў. | Папоўніце баланс OAuth і пачніце новы ўваход. |
| 429 | Перавышаны ліміт запытаў або спроб пацверджання. | Выконвайце Retry-After і паўтарайце з выпадковай дадатковай затрымкай. |
Пытанні і адказы
Калі спісваецца аплата?
Пасля паспяховай выдачы токена. Першая сесія лічыцца рэгістрацыяй, наступныя — уваходамі. Няўдалыя і скасаваныя спробы, refresh, UserInfo і logout бясплатныя.
Ці можна выкарыстоўваць толькі email?
Так. Bototeka падтрымлівае рэгістрацыю па email, аднаразовыя коды, пацверджанне адраса і аднаўленне пароля без сацыяльных правайдараў.
Ці можна падключыць SPA?
Так, як public client з PKCE і кароткачасовым access token у памяці. Для рабочага запуску лепш сервер або BFF з HttpOnly-сесіяй.
Што захоўваць як ID кліента?
Захоўвайце пару issuer і sub. Email можа змяніцца і не з'яўляецца пастаянным ідэнтыфікатарам.
Як змяніць сакрэт?
Стварыце або абнавіце API-ключ у наладах кампаніі. Адразу скапіруйце новы сакрэт, абнавіце налады сервера і адклічце стары доступ.