Sürətli başlanğıc
Bototeka Authorization Code və PKCE S256 dəstəkləyən istənilən OpenID Connect kitabxanası ilə işləyir.
Tətbiq yaradın
Xidmətin adını, geri dönüş ünvanını və istəyə görə loqonu daxil edin. Google, Apple və Yandex geri dönüşlərini Bototeka idarə edir.
Giriş məlumatlarını saxlayın
Client ID və Client Secret-i kopyalayın. Məxfi açar yalnız bir dəfə göstərilir.
OIDC-ni qurun
Kitabxanaya issuer ünvanını verin. Digər endpoint-ləri avtomatik tapacaq.
Girişi yoxlayın
Girişi başladın, state və nonce-u yoxlayın, kodu dəyişdirin və yerli sessiya yaradın.
- 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 nümunəsi
- https://service.example/auth/callback
Bağlantı yoxlaması
Sahib və administrator üçün balanssız əlçatandır
Bu test Bototeka parametrlərini və provayder endpoint-inin əlçatanlığını yoxlayır. İstifadəçinin interaktiv girişi ayrıca yoxlanılır.
OAuth parametrlərini açınGiriş və tokenlər
Serveriniz PKCE, state və nonce yaradır, istifadəçini Bototeka-ya yönləndirir və qısa müddətli avtorizasiya kodu alır.
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'Qeydiyyat məlumatları API vasitəsilə
Şirkət parametrlərində API açarı yaradın. Şirkətinizin tətbiqləri üçün müştəriləri və hadisələri sorğulayın.
/applications/{applicationId}/customerssub, təsdiqlənmiş email, ad və fəaliyyət vaxtlarını qaytarır.
/applications/{applicationId}/eventsQeydiyyat və ya giriş, məbləğ, valyuta, status və hadisə vaxtını qaytarır.
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'Oxumaq üçün identity:read tələb olunur. Açarı Bearer token kimi göndərin və serverdə saxlayın.
Webhook-lar
Şirkət parametrlərində hadisələrə abunə olun. Ünvan HTTPS istifadə etməlidir. İmza açarı yalnız bir dəfə göstərilir.
identity.registration.completed.v1Qeydiyyat tamamlanıb və istifadə jurnalında qeydə alınıb.
identity.login.completed.v1Təkrar giriş tamamlanıb və istifadə jurnalında qeydə alınıb.
Hadisə ən azı bir dəfə çatdırılır. event ID ilə təkrarları ayırın, hadisələri istənilən ardıcıllıqda qəbul edin və yalnız saxladıqdan sonra 2xx qaytarın.
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);
}İşə başlamazdan əvvəl yoxlayın
- Dəqiq HTTPS Redirect URI istifadə edin. İstənilən ünvana geri dönüşə icazə verməyin.
- Hər cəhd üçün yeni state, nonce və PKCE verifier yaradın və server sessiyasında saxlayın.
- Client Secret, API açarları, access token və refresh token-i brauzerdə və ya mobil analitikada saxlamayın.
- offline_access-i yalnız serverinizə uzunmüddətli sessiya lazım olduqda istəyin.
- Webhook imzasını xam sorğu gövdəsi ilə yoxlayın və təkrar çatdırılmanı təhlükəsiz emal edin.
Xətalar və bərpa
invalid_requestNə baş verdi
Tələb olunan parametr yoxdur və ya yanlışdır.
Nə etməli
Redirect URI, PKCE, state, nonce və Content-Type-ı yoxlayın.
invalid_grantNə baş verdi
Kodun vaxtı bitib, istifadə olunub və ya verifier ilə uyğun gəlmir.
Nə etməli
Yeni giriş başladın. Eyni kodu yenidən dəyişdirməyin.
temporarily_unavailableNə baş verdi
Tətbiqin balansında kifayət qədər vəsait yoxdur.
Nə etməli
OAuth balansını artırın və yeni giriş başladın.
429Nə baş verdi
Sorğu və ya təsdiq cəhdlərinin limiti aşılıb.
Nə etməli
Retry-After-a əməl edin və təsadüfi əlavə gecikmə ilə təkrar sınayın.
| Kod | Nə baş verdi | Nə etməli |
|---|---|---|
| invalid_request | Tələb olunan parametr yoxdur və ya yanlışdır. | Redirect URI, PKCE, state, nonce və Content-Type-ı yoxlayın. |
| invalid_grant | Kodun vaxtı bitib, istifadə olunub və ya verifier ilə uyğun gəlmir. | Yeni giriş başladın. Eyni kodu yenidən dəyişdirməyin. |
| temporarily_unavailable | Tətbiqin balansında kifayət qədər vəsait yoxdur. | OAuth balansını artırın və yeni giriş başladın. |
| 429 | Sorğu və ya təsdiq cəhdlərinin limiti aşılıb. | Retry-After-a əməl edin və təsadüfi əlavə gecikmə ilə təkrar sınayın. |
Suallar və cavablar
Ödəniş nə vaxt tutulur?
Token uğurla verildikdən sonra. İlk sessiya qeydiyyat, sonrakılar giriş sayılır. Uğursuz və ləğv edilmiş cəhdlər, refresh, UserInfo və logout ödənişsizdir.
Yalnız email istifadə edə bilərəm?
Bəli. Bototeka sosial provayderlərsiz email qeydiyyatı, birdəfəlik kodlar, ünvan təsdiqi və parol bərpasını dəstəkləyir.
SPA qoşa bilərəm?
Bəli. PKCE və yaddaşda saxlanan qısa müddətli access token ilə public client kimi. İş mühiti üçün server və ya HttpOnly sessiyalı BFF üstün tutulur.
Müştəri ID-si kimi nə saxlamalıyam?
issuer və sub cütünü saxlayın. Email dəyişə bilər və sabit identifikator deyil.
Məxfi açarı necə dəyişirəm?
Şirkət parametrlərində API açarı yaradın və ya dəyişin. Yeni məxfi açarı dərhal kopyalayın, server parametrlərini yeniləyin və köhnə girişi ləğv edin.