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 жөндөөлөрүн ачуу