Bototeka arkaly girişi birikdiriň

OpenID Connect we PKCE ulanyň. Kody tokenlere çalşyň we profili UserInfo arkaly alyň.

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"]
}

Çalt başlangyç

Bototeka Authorization Code we PKCE S256 goldaýan islendik OpenID Connect kitaphanasy bilen işleýär.

  1. 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.

  2. Giriş maglumatlaryny saklaň

    Client ID we Client Secret göçüriň. Gizlin açar diňe bir gezek görkezilýär.

  3. OIDC sazlaň

    Kitaphana issuer salgysyny beriň. Ol beýleki endpoint-leri awtomatiki tapar.

  4. 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çmak

Giriş 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.

Ygtyýarlandyryş URL-yny döretmek
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());
Kody tokenlere çalyşmak
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'
Profili almak
curl 'https://bototeka.com/api/oauth/userinfo' \
  --header 'Authorization: Bearer ACCESS_TOKEN'
Yzyna gaýdandan soň: state deňeşdiriň, kody diňe bir gezek çalşyň, ID Token goluny JWKS arkaly, soň issuer, audience, möhletini we nonce barlaň. Ulanyjyny email bilen däl-de, iss + sub jübüti bilen saklaň.

Hasaba alyş maglumatlary API arkaly

Kompaniýanyň sazlamalarynda API açaryny dörediň we kompaniýaňyzyň programmalarynyň müşderilerini ýa-da wakalaryny soraň.

GET/applications/{applicationId}/customers

sub, tassyklanan email, at we işjeňlik wagtlaryny gaýtarýar.

GET/applications/{applicationId}/events

Hasaba alyş ýa-da giriş, möçber, pul birligi, ýagdaý we wakanyň wagtyny gaýtarýar.

Programmanyň müşderilerini almak
curl 'https://api.bototeka.com/api/identity/v1/applications/APPLICATION_ID/customers?limit=50' \
  --header 'Authorization: Bearer btk_v1_YOUR_API_KEY'
Hasaba alyş we giriş wakalaryny almak
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.v1

Hasaba alyş tamamlandy we ulanyş žurnalyna ýazyldy.

identity.login.completed.v1

Gaý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ň.

Webhugyň goluny barlamak
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_request

Näme boldy

Hökmany parametr ýok ýa-da nädogry.

Näme etmeli

Redirect URI, PKCE, state, nonce we Content-Type barlaň.

invalid_grant

Nä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_unavailable

Näme boldy

Programmanyň balansynda ýeterlik serişde ýok.

Näme etmeli

OAuth balansyny dolduryň we täze giriş başladyň.

429

Nä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ň.

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ň.

Hyzmatyňyza giriş birikdiriň

OAuth sazlamalaryny açmak