BizKitHubDocs

API klíče

Pro zavolání libovolného API endpointu z externího systému organizace je vždy potřeba předat autorizační API klíč.

📋 Způsoby předání API klíče

API klíč akceptujeme jako vlastnost apiKey buď jako URL query parametr, nebo jako součást BODY requestu. API klíč akceptují všechny HTTP metody oběma způsoby (pokud jsou dostupné).

Formát API klíče

Pro usnadnění orientace mezi klíči je řadíme do několika skupin, přičemž typ klíče lze přímo poznat z jeho formátu.

Příklad validního formátu API klíče:

PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE

*Tento API klíč neexistuje, slouží jen pro demonstraci formátu.

Skupinu API klíčů definují první 4 znaky klíče. V tomto případě to byl prefix PROD.

PROD

Produkční klíč

Limit požadavků
500 000 / min

Používaný ve vaší reálné aplikaci na webovém serveru

Speciální poznámky:

Při detekci hromadného scanování dat robotem můžeme nastavit dočasné rychlostní limity a provést blokaci konkrétního uživatele. Aktivitu logujeme částečně.

DEV_

Vývojářský klíč

Limit požadavků
1 000 / min

Každý váš člen (member, vývojář) má vlastní API klíč

Speciální poznámky:

Při detekci hromadného scanování dat zákazníků, objednávek a dalších citlivých dat posíláme upozornění správci organizace. Probíhá podrobné logování aktivity.

ROOT

Systémový klíč

Limit požadavků
∞

Systémový klíč pro organizaci BizKitHub. Umí obcházet všechna omezení a oprávnění

Speciální poznámky:

Nemá nastavené žádné omezení. Při detekci neobvyklé aktivity můžeme poslat upozornění správci organizace.

Pravidla pro generování API klíče

  • Klíč splňuje regulární výraz /^(PROD|DEV_|ROOT)([a-zA-Z0-9]{28})$/
  • Délka celého klíče je vždy 32 znaků
  • Celý klíč je vždy unikátní v celé BizKitHub databázi napříč organizacemi
  • Obsahuje prefix s typem klíče, který má právě 4 znaky
  • Uvnitř klíče obsahuje 28 znaků
  • Znaky uvnitř klíče vznikají náhodným generátorem
  • Znaky uvnitř klíče mají různou velikost, mohou obsahovat znaky anglické abecedy a čísla

🔧 Kontrola formátu

Pro validaci formátu použijte funkci parseApiKey(apiKey).

Ověření klíčů

Při zpracování všech API požadavků systém pokaždé ověřuje předaný API klíč. Všechny vystavené klíče včetně historie a jejich nastavení ukládáme do systémové tabulkycas__organisation_api_key, která byla navržena pro vysoký výkon čtení a aktualizace statistik použití.

Workflow ověření:

1

Ověření předání klíče (pokud nebyl klíč předán, vyhazujeme chybu "Parameter apiKey is always required.")

2

Ověření formátu klíče (použijeme regulární výraz pro ověření formátu dle této specifikace)

3

Ověření existence klíče v databázi (požádáme centrální registr klíčů o vydání záznamu o klíči a jeho nastavení)

4

Ověření expirace klíče (na základě databázového záznamu ověříme, zda je klíč aktivní a nebyl zatím expirován)

5

Ověření rate-limit počtu požadavků (byl překročen maximální počet požadavků na API s tímto klíčem?)

6

Načtení a ověření rolí (podle typu klíče požádáme databázi o nastavené role, a ověříme, zda můžeme provolat konkrétní API endpoint)

7

Provedení API požadavku (pokud všechna pravidla prochází korektně, provedeme API požadavek)

Omezení klíčů

Každý vygenerovaný klíč podléhá předem nastavenému omezení, které bylo navrženo pro ochranu dat organizace a zajištění stability hlavního systému.

SkupinaOmezení počtu requestůSpeciální komentář
PROD500 000 / minPři detekci hromadného scanování dat robotem můžeme nastavit dočasné rychlostní limity a provést blokaci konkrétního uživatele. Aktivitu logujeme částečně.
DEV_1 000 / minPři detekci hromadného scanování dat zákazníků, objednávek a dalších citlivých dat posíláme upozornění správci organizace. Probíhá podrobné logování aktivity.
ROOT∞Nemá nastavené žádné omezení. Při detekci neobvyklé aktivity můžeme poslat upozornění správci organizace.

Bezpečnostní doporučení

✅ Doporučené postupy

  • • Nikdy nevystavujte API klíč v klientském kódu
  • • Používejte HTTPS pro všechny API požadavky
  • • Pravidelně rotujte API klíče
  • • Monitorujte využití API klíčů
  • • Používejte DEV klíče pro vývoj a testování

❌ Co se vyhnout

  • • Ukládání klíčů v repozitářích
  • • Sdílení klíčů mezi vývojáři
  • • Používání PROD klíčů pro testování
  • • Logování API klíčů do souborů
  • • Odesílání klíčů přes nezabezpečené kanály

Příklady použití

URL Query parametr

GET https://api.bizkithub.com/v1/users?apiKey=PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE

POST Body

POST https://api.bizkithub.com/v1/users
Content-Type: application/json

{
  "apiKey": "PRODPGrFxpGEtrOZfuWhnoJohUYBXuOE",
  "email": "user@example.com",
  "name": "John Doe"
}

JavaScript/Node.js

const response = await fetch('https://api.bizkithub.com/v1/users', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  }
});

// Nebo s query parametrem
const response = await fetch('https://api.bizkithub.com/v1/users?apiKey=YOUR_API_KEY');

Jak získat API klíč?

API klíče můžete spravovat v administračním rozhraní BizKitHub platformy.

Přejít do administracePrůvodce pro začátečníky