Bototeka арқылы кіруді қосыңыз

OpenID Connect пен PKCE қолданыңыз. Кодты токендерге айырбастап, профильді UserInfo арқылы алыңыз.

openid-configuration
{
  "issuer": "https://bototeka.com/api",
  "authorization_endpoint": "https://bototeka.com/api/oauth/authorize",
  "token_endpoint": "https://bototeka.com/api/oauth/token",
  "userinfo_endpoint": "https://bototeka.com/api/oauth/userinfo",
  "scopes_supported": ["openid", "email", "profile", "offline_access"]
}

Жылдам бастау

Bototeka Authorization Code және PKCE S256 қолдайтын кез келген OpenID Connect кітапханасымен жұмыс істейді.

  1. Қолданба жасаңыз

    Сервис атауын, қайтару мекенжайын және қажет болса логотипті көрсетіңіз. Google, Apple және Yandex қайтаруларын Bototeka басқарады.

  2. Тіркелгі деректерін сақтаңыз

    Client ID және Client Secret көшіріңіз. Құпия кілт тек бір рет көрсетіледі.

  3. OIDC баптаңыз

    Кітапханаға issuer мекенжайын беріңіз. Басқа endpoint-терді ол автоматты түрде табады.

  4. Кіруді тексеріңіз

    Кіруді бастаңыз, 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-ға жібереді және тек қысқа мерзімді авторизация кодын алады.

Авторизация URL-ын жасау
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'
Қайтып келгеннен кейін: state салыстырыңыз, кодты бір рет айырбастаңыз, ID Token қолтаңбасын JWKS арқылы, содан кейін issuer, audience, жарамдылық мерзімі мен nonce тексеріңіз. Пайдаланушыны email арқылы емес, iss + sub жұбымен сақтаңыз.

Тіркелу деректері API арқылы

Компания баптауларында API кілтін жасап, компанияңыздың қолданбалары үшін клиенттерді немесе оқиғаларды сұратыңыз.

GET/applications/{applicationId}/customers

sub, расталған email, ат пен белсенділік уақыттарын қайтарады.

GET/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 талабын сақтап, кездейсоқ қосымша кідіріспен қайталаңыз.

Сұрақтар мен жауаптар

Төлем қашан алынады?

Токен сәтті берілгеннен кейін. Алғашқы сессия тіркелу, кейінгілері кіру болып саналады. Сәтсіз және тоқтатылған әрекеттер, refresh, UserInfo және logout тегін.

Тек email қолдануға бола ма?

Иә. Bototeka әлеуметтік провайдерлерсіз email арқылы тіркелуді, бір реттік кодтарды, мекенжайды растауды және құпиясөзді қалпына келтіруді қолдайды.

SPA қосуға бола ма?

Иә, PKCE және жадтағы қысқа мерзімді access token қолданатын public client ретінде. Нақты іске қосу үшін сервер немесе HttpOnly сессиясы бар BFF ұсынылады.

Клиент ID-і ретінде нені сақтау керек?

issuer және sub жұбын сақтаңыз. Email өзгеруі мүмкін және тұрақты идентификатор емес.

Құпия кілтті қалай ауыстырамын?

Компания баптауларында API кілтін жасаңыз немесе ауыстырыңыз. Жаңа құпия кілтті бірден көшіріп, сервер баптауларын жаңартыңыз және ескі қолжетімділікті қайтарып алыңыз.

Сервисіңізге кіруді қосыңыз

OAuth баптауларын ашу