Çalt başlangyç
Bototeka Authorization Code we PKCE S256 goldaýan islendik OpenID Connect kitaphanasy bilen işleýär.
Programma dörediň
Hyzmatyň adyny, yzyna gaýdyş salgysyny we isleseňiz nyşany görkeziň. Google, Apple we Yandex-den gaýdyşlary Bototeka dolandyrýar.
Giriş maglumatlaryny saklaň
Client ID we Client Secret göçüriň. Gizlin açar diňe bir gezek görkezilýär.
OIDC sazlaň
Kitaphana issuer salgysyny beriň. Ol beýleki endpoint-leri awtomatiki tapar.
Girişi barlaň
Girişi başladyň, state we nonce barlaň, kody çalşyň we ýerli sessiýa dörediň.
- 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 mysaly
- https://service.example/auth/callback
Birikmäni barlamak
Eýe we administrator üçin balanssyz elýeterli
Bu synag Bototeka sazlamalaryny we üpjün edijiniň endpoint-iniň elýeterliligini barlaýar. Ulanyjynyň interaktiw girişi aýratyn synagdan geçirilýär.
OAuth sazlamalaryny açmakGiriş we tokenler
Serweriňiz PKCE, state we nonce döredýär, ulanyjyny Bototeka iberýär we diňe gysga möhletli ygtyýarlandyryş koduny alýar.
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'Hasaba alyş maglumatlary API arkaly
Kompaniýanyň sazlamalarynda API açaryny dörediň we kompaniýaňyzyň programmalarynyň müşderilerini ýa-da wakalaryny soraň.
/applications/{applicationId}/customerssub, tassyklanan email, at we işjeňlik wagtlaryny gaýtarýar.
/applications/{applicationId}/eventsHasaba alyş ýa-da giriş, möçber, pul birligi, ýagdaý we wakanyň wagtyny gaýtarýar.
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'Okamak üçin identity:read gerek. Açary Bearer token hökmünde iberiň we serwerde saklaň.
Webhuklar
Kompaniýanyň sazlamalarynda wakalara ýazylyň. Salgy HTTPS ulanmalydyr. Gol üçin gizlin açar diňe bir gezek görkezilýär.
identity.registration.completed.v1Hasaba alyş tamamlandy we ulanyş žurnalyna ýazyldy.
identity.login.completed.v1Gaýtadan giriş tamamlandy we ulanyş žurnalyna ýazyldy.
Eltip bermek azyndan bir gezek ýerine ýetirilýär. Gaýtalananlary event ID boýunça aýryň, wakalary islendik tertipde kabul ediň we diňe saklandan soň 2xx gaýtaryň.
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);
}Işe başlamazdan öň barlaglar
- Takyk HTTPS Redirect URI ulanyň. Islendik salgy üçin yzyna gaýdyşy kabul etmäň.
- Her synanyşyk üçin täze state, nonce we PKCE verifier dörediň we serwer sessiýasynda saklaň.
- Client Secret, API açarlaryny, access token we refresh token-i brauzerde ýa-da mobil analitikada saklamaň.
- offline_access-i diňe serweriňize hakykatdanam uzak sessiýa gerek bolanda soraň.
- Webhuk gollaryny soragyň işlenmedik göwresi boýunça barlaň we gaýtadan eltip bermäni howpsuz işlediň.
Ýalňyşlyklar we dikeltmek
invalid_requestNäme boldy
Hökmany parametr ýok ýa-da nädogry.
Näme etmeli
Redirect URI, PKCE, state, nonce we Content-Type barlaň.
invalid_grantNäme boldy
Kodyň möhleti geçdi, ulanyldy ýa-da verifier bilen gabat gelenok.
Näme etmeli
Täze giriş başladyň. Şol kody gaýtadan çalyşmaň.
temporarily_unavailableNäme boldy
Programmanyň balansynda ýeterlik serişde ýok.
Näme etmeli
OAuth balansyny dolduryň we täze giriş başladyň.
429Näme boldy
Sorag ýa-da tassyklama synanyşyklarynyň çägi geçildi.
Näme etmeli
Retry-After-i berjaý ediň we tötänleýin goşmaça garaşmak bilen gaýtadan synanyşyň.
| Kod | Näme boldy | Näme etmeli |
|---|---|---|
| invalid_request | Hökmany parametr ýok ýa-da nädogry. | Redirect URI, PKCE, state, nonce we Content-Type barlaň. |
| invalid_grant | Kodyň möhleti geçdi, ulanyldy ýa-da verifier bilen gabat gelenok. | Täze giriş başladyň. Şol kody gaýtadan çalyşmaň. |
| temporarily_unavailable | Programmanyň balansynda ýeterlik serişde ýok. | OAuth balansyny dolduryň we täze giriş başladyň. |
| 429 | Sorag ýa-da tassyklama synanyşyklarynyň çägi geçildi. | Retry-After-i berjaý ediň we tötänleýin goşmaça garaşmak bilen gaýtadan synanyşyň. |
Soraglar we jogaplar
Töleg haçan alynýar?
Token üstünlikli berlenden soň. Ilkinji sessiýa hasaba alyş, soňky sessiýalar giriş hasaplanýar. Şowsuz ýa-da ýatyrylan synanyşyklar, refresh, UserInfo we logout mugt.
Diňe email ulanyp bolarmy?
Hawa. Bototeka sosial üpjün edijilersiz email arkaly hasaba almagy, bir gezeklik kodlary, salgyny tassyklamagy we paroly dikeltmegi goldaýar.
SPA birikdirip bolarmy?
Hawa, PKCE we ýatda saklanýan gysga möhletli access token bilen public client hökmünde. Hakyky iş üçin serwer ýa-da HttpOnly sessiýaly BFF maslahat berilýär.
Müşderi ID-si hökmünde näme saklamaly?
issuer we sub jübütini saklaň. Email üýtgäp biler we hemişelik kesgitleýji däldir.
Gizlin açary nädip çalyşmaly?
Kompaniýanyň sazlamalarynda API açaryny dörediň ýa-da täzeläň. Täze gizlin açary derrew göçüriň, serwer sazlamalaryny täzeläň we köne girişi ýatyryň.