Zum Inhalt springen
Garanify

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.

ArtFormatWoDarfSenden
Secret Keygfy_sk_…Ihr ServerAlles: Shop, Produkte, Regeln, Schlüssel, Lizenz, WebhooksHeader Authorization: Bearer
Publishable Keygfy_pk_<shop>_…Browser, SnippetNur lesen: öffentliche Etiketten und Einstellungen, nur von den Domains des ShopsQuery ?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

  1. Neuen Schlüssel holen: POST …/keys/{key}/rotate. Der alte gilt noch graceSeconds lang (Standard 1 Tag, höchstens 7).
  2. Neuen Schlüssel ausrollen.
  3. 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()