Developer
Test ModeTest Mode Sign In Get started
DeveloperDeveloper / AuthentifizierungAuthentication

AuthentifizierungAuthentication

Jeder API-Call erfordert einen gültigen API-Key im Authorization-Header. BEEP! verwendet ein Publishable/Secret-Key-Modell mit Test- und Live-Modus.

Every API call requires a valid API key in the Authorization header. BEEP! uses a Publishable/Secret key model with Test and Live mode.

SchlüsseltypenKey Types

Dein Dashboard enthält zwei Schlüssel pro Modus (Test & Live):

Your dashboard contains two keys per mode (Test & Live):

TypType Prefix VerwendungUsage
Publishable Key (pk) bk_{mode}_pk_… Client-seitig erlaubt, identifiziert deinen AccountAllowed client-side, identifies your account
Secret Key (sk) bk_{mode}_sk_… Nur serverseitig! Voller API-Zugang, nie committenServer-side only! Full API access, never commit
Secret Keys niemals im Client-Code, in Git oder in Logs verwenden. Sollte ein SK kompromittiert sein, rotiere ihn sofort im Dashboard unter "Schluessel verwalten".Never use Secret Keys in client code, Git or logs. If a SK is compromised, rotate it immediately in the Dashboard under "Manage keys".

Test Mode vs. Live ModeTest Mode vs. Live Mode

Jeder Account hat zwei isolierte Umgebungen:

Every account has two isolated environments:

EigenschaftProperty Test ModeTest Mode Live Mode
Key-Prefix bk_test_ bk_live_
DatenData Sandbox-Mock-DatenSandbox mock data Echte Store-DatenReal store data
ZahlungenPayments PSP Test Mode Echte TransaktionenReal transactions
Rate Limits UnbegrenztUnlimited PaketabhängigPackage-dependent
VoraussetzungRequirement Kostenloser AccountFree account Aktives Abo + manueller ReviewActive subscription + manual review

Authorization Header

Sende den Key als Bearer-Token im Authorization-Header:

Send the key as a Bearer token in the Authorization header:

HTTP Header
Authorization: Bearer bk_test_sk_A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
Optionaler Header: X-Beep-Store-Id: {storeId}, damit kannst du Store-spezifische Calls machen, ohne die storeId im Body zu übergeben.
Optional header: X-Beep-Store-Id: {storeId} lets you make store-specific calls without passing storeId in the body.

Key-Format (Anatomie)Key Format (Anatomy)

Jeder Key folgt diesem Muster:

Every key follows this pattern:

Format
bk_{mode}_{variant}_{keyId}_{secret} Beispiel: bk_test_sk_A1B2C3D4_E5F6G7H8I9J0K1L2M3N4O5P6 bk → BEEP Key Prefix (always "bk") test → Mode: "test" or "live" sk → Variant: "pk" (publishable) or "sk" (secret) A1B2C3D4 → Key ID (8 chars, identifies the key) E5F6… → Secret segment (cryptographically secure, stored as SHA-256 hash)

SicherheitshinweiseSecurity Notes

  • Secret Keys werden nie im Klartext gespeichert, nur als SHA-256 Hash.Secret Keys are never stored in plain text, only as SHA-256 hash.
  • Validierung erfolgt ueber crypto.timingSafeEqual (verhindert Timing-Attacks).Validation uses crypto.timingSafeEqual (prevents timing attacks).
  • Rotiere Keys regelmaessig ueber das Dashboard: "Schluessel rotieren".Rotate keys regularly via the Dashboard: "Rotate keys".
  • Bei Kompromittierung: Key im Dashboard sofort widerrufen. Der alte Key wird instant ungueltig.If compromised: revoke the key immediately in the Dashboard. The old key becomes invalid instantly.
  • Live-Keys benoetigen einen manuellen Review durch das BEEP!-Team (Aktivierungsantrag).Live keys require a manual review by the BEEP! team (activation request).

Paket-BerechtigungenPackage Permissions

Welche Endpoints dein Key aufrufen darf, hängt vom Paket ab:

Which endpoints your key may call depends on your package:

PaketPackage Endpoints
DISCOVER Stores, Produkte, Katalog (fetchStores, fetchStore, fetchProducts, fetchProduct, insertProduct, registerProductToStore, uploadImageToProduct, bulkImportProducts, submitStoreRegistration)Stores, products, catalog (fetchStores, fetchStore, fetchProducts, fetchProduct, insertProduct, registerProductToStore, uploadImageToProduct, bulkImportProducts, submitStoreRegistration)
ASSIST = DISCOVER + QR-Zonen, In-Store-ChatQR zones, in-store chat
GO = DISCOVER + AngeboteOffers (createOffer, updateOffer, deleteOffer, getManagerOffers, cloneOffer) + Click & Collect + Loyalty (createLoyaltyProgram, updateLoyaltyProgram, getLoyaltyProgram, getStoreLoyaltyPrograms, getLoyaltyPrograms, enrollInLoyaltyProgram, addLoyaltyPoints, redeemLoyaltyPoints, getCustomerBalance, getLoyaltyAnalytics)Loyalty (createLoyaltyProgram, updateLoyaltyProgram, getLoyaltyProgram, getStoreLoyaltyPrograms, getLoyaltyPrograms, enrollInLoyaltyProgram, addLoyaltyPoints, redeemLoyaltyPoints, getCustomerBalance, getLoyaltyAnalytics)
GROW = GO + Scan & Go (checkIn, startCheckout, fetchPurchase, fetchPurchaseHistory, verifySecurityTagDeactivation) + POS/ERP/PSP-Sync (syncPOS, pushToPOS, syncERP, pushToERP, configurePSP, processPayment, refundPayment) + Loyalty Cashback, Custom Rewards, getLoyaltyWebhookEvents, ASSIST-Features (QR-Zonen, In-Store-Chat)Loyalty Cashback, Custom Rewards, getLoyaltyWebhookEvents, ASSIST features (QR zones, in-store chat)
PRIME Alle Endpoints + Analytics (getAnalytics, exportSalesData, exportReceiptData) + Externe Loyalty (syncExternalLoyalty) + Premium SupportAll endpoints + Analytics (getAnalytics, exportSalesData, exportReceiptData) + External Loyalty (syncExternalLoyalty) + Premium support

IntegrationsarchitekturIntegration Architecture

Die BEEP!-Plattform unterscheidet zwei Integrationspfade:

The BEEP! platform has two distinct integration paths:

IntegrationspfadIntegration Path AuthentifizierungAuth DatenzugriffData Access Wer?Who?
Developer API (diese Docs)Developer API (these docs) bk_{mode}_sk_… API-Key im Bearer-HeaderAPI key in Bearer header Via BEEP! API (/api/v1/{action})Via BEEP! API (/api/v1/{action}) Drittanbieter, eigene POS/ERP/SystemeThird-party, custom POS/ERP/systems
BEEP! Apps (intern)BEEP! Apps (internal) Auth Token (kein bk_*-Key)Auth Token (no bk_* key) Direkt auf BEEP! CloudDirect access to BEEP! Cloud BEEP!-App, Haendler-AppBEEP! App, Merchant App
Als externer Entwickler verwendest du immer den Developer API-Pfad mit API-Key. Die BEEP!-App selbst nutzt keine Developer-API-Keys, sondern greift mit internen Auth-Tokens direkt auf die BEEP! Cloud zu.As an external developer you always use the Developer API path with an API key. The BEEP! apps do not use developer API keys. They access the BEEP! Cloud directly with internal auth tokens.