Authentifizierung
Zwei Schlüsselarten je Shop: einer, der schreibt und geheim bleibt, und einer, der nur liest und öffentlich sein darf.
Die API ist gebaut und getestet. Das Hosting unter api.garanify.com ist in Vorbereitung; bis dahin läuft sie lokal. Schlüssel gibt es auf Anfrage.
| Art | Format | Wo | Darf | Senden |
|---|---|---|---|---|
| Secret Key | gfy_sk_… | Ihr Server | Alles: Shop, Produkte, Regeln, Schlüssel, Lizenz, Webhooks | Header Authorization: Bearer |
| Publishable Key | gfy_pk_<shop>_… | Browser, Snippet | Nur lesen: öffentliche Etiketten und Einstellungen, nur von den Domains des Shops | Query ?key= oder Header |
Secret Key
Senden Sie ihn bei jeder Anfrage im Header. In der URL lehnen wir Secret Keys ab (key_in_query), weil URLs in Logs landen. Live-Secret-Keys bekommen keine CORS-Header: Browser können mit ihnen nicht aufrufen. Nur Test-Secret-Keys (gfy_sk_test_…) erhalten CORS, damit „Ausprobieren“ in dieser Doku funktioniert.
curl "https://api.garanify.com/v1/me" \
-H "Authorization: Bearer $GARANIFY_SECRET_KEY"import { Garanify } from '@garanify/sdk';
const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const me = await garanify.me();<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$me = $garanify->me();import os, requests
res = requests.get(
"https://api.garanify.com/v1/me",
headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
timeout=10,
)
res.raise_for_status()
data = res.json()Publishable Key und Domain-Bindung
Der Publishable Key gilt nur für Anfragen, deren Origin (oder Referer) auf einer Domain des Shops liegt, Subdomains eingeschlossen. Andere Herkünfte bekommen 403 origin_not_allowed und keine CORS-Freigabe. Übergeben Sie ihn als ?key=: Dann ist die Anfrage ein einfacher GET ohne Preflight und lässt sich cachen.
Der Schlüssel ist kein Geheimnis. Er verrät nur, was ohnehin auf Ihrer Produktseite steht. Die Shop-ID steckt im Schlüssel, damit das Snippet nur ein Attribut braucht.
Testmodus
Ein Test-Shop hat eigene Schlüssel mit test_ im Präfix: gfy_sk_test_… und gfy_pk_test_<shop>_…. Er ist vollständig von Ihren Live-Shops getrennt und hat alle Funktionen ohne Lizenz (Tarif test). GET /v1/me und jeder Shop zeigen livemode: false, Webhook-Ereignisse ebenso. Shops, die ein Test-Schlüssel anlegt, sind wieder Test-Shops.
Lizenzen verknüpfen geht nur im Live-Modus (403 live_key_required). Prüfen Sie im Code livemode, bevor Sie Ereignisse in Ihr Produktivsystem übernehmen.
Request-Id
Jede Antwort trägt einen Header Request-Id (req_…), Fehler zusätzlich das Feld requestId. Senden Sie selbst einen Request-Id (1 bis 64 Zeichen aus A–Z a–z 0–9 . _ -), übernehmen wir ihn. Geben Sie die ID an, wenn Sie den Support fragen.
Speicherung
Wir speichern nur einen Hash jedes Schlüssels (HMAC-SHA256). Nach dem Anlegen sehen Sie das Geheimnis nie wieder, nur einen Hinweis mit den letzten vier Zeichen und den Tag der letzten Nutzung.
Rotation und Sperren
- Neuen Schlüssel holen:
POST …/keys/{key}/rotate. Der alte gilt nochgraceSecondslang (Standard 1 Tag, höchstens 7). - Neuen Schlüssel ausrollen.
- Bei Verdacht sofort sperren:
DELETE …/keys/{key}. Den letzten aktiven Secret Key können Sie nicht sperren (last_secret_key).
curl -X POST "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/keys/key_9hVb2mQx7Lp1/rotate" \
-H "Authorization: Bearer $GARANIFY_SECRET_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"graceSeconds":3600}'import { Garanify } from '@garanify/sdk';
const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const key = await garanify.keys.rotate('key_9hVb2mQx7Lp1', {
graceSeconds: 3600
});<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$key = $garanify->keys->rotate('key_9hVb2mQx7Lp1', [
'graceSeconds' => 3600,
]);import os, uuid, requests
res = requests.post(
"https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/keys/key_9hVb2mQx7Lp1/rotate",
headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"graceSeconds": 3600,
},
timeout=10,
)
res.raise_for_status()
data = res.json()Tarif und Lizenz
Ohne Lizenz läuft der Shop mit Free. Mit PUT …/license verknüpfen Sie einen Pro- oder Agentur-Schlüssel (GRFY-…) aus Ihrem Garanify-Konto; er wird für die erste Domain des Shops aktiviert. Grenzen je Tarif unter Limits.
curl -X PUT "https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/license" \
-H "Authorization: Bearer $GARANIFY_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"key":"GRFY-ABCD-EFGH-JKMN-PQRS"}'import { Garanify } from '@garanify/sdk';
const garanify = new Garanify({ apiKey: process.env.GARANIFY_SECRET_KEY });
const plan = await garanify.license.link('GRFY-ABCD-EFGH-JKMN-PQRS');<?php
// composer require garanify/sdk guzzlehttp/guzzle
$factory = new GuzzleHttp\Psr7\HttpFactory();
$garanify = new Garanify\Garanify(getenv('GARANIFY_SECRET_KEY'), ['httpClient' => new GuzzleHttp\Client(), 'requestFactory' => $factory, 'streamFactory' => $factory]);
$plan = $garanify->license->link('GRFY-ABCD-EFGH-JKMN-PQRS');import os, requests
res = requests.put(
"https://api.garanify.com/v1/shops/shp_4kq8Zt2mWc9x/license",
headers={"Authorization": f"Bearer {os.environ['GARANIFY_SECRET_KEY']}"},
json={
"key": "GRFY-ABCD-EFGH-JKMN-PQRS",
},
timeout=10,
)
res.raise_for_status()
data = res.json()