Authentication
Two key types per shop: one that writes and stays secret, one that only reads and may be public.
The API is built and tested. Hosting at api.garanify.com is in preparation; until then it runs locally. Keys are available on request.
| Type | Format | Where | Can | Send as |
|---|---|---|---|---|
| Secret key | gfy_sk_… | Your server | Everything: shop, products, rules, keys, licence, webhooks | Header Authorization: Bearer |
| Publishable key | gfy_pk_<shop>_… | Browser, snippet | Read only: public labels and settings, only from the domains of the shop | Query ?key= or header |
Secret key
Send it in the header with every request. We reject secret keys in the URL (key_in_query) because URLs end up in logs. Live secret keys get no CORS headers, so browsers cannot call with them. Only test secret keys (gfy_sk_test_…) get CORS, so that “Try it” in these docs works.
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 and domain binding
The publishable key only works for requests whose Origin (or Referer) is on a domain of the shop, subdomains included. Other origins get 403 origin_not_allowed and no CORS permission. Pass it as ?key=: the request is then a simple GET without preflight and can be cached.
The key is not a secret. It only reveals what your product page shows anyway. The shop ID is part of the key so that the snippet needs only one attribute.
Test mode
A test shop has its own keys with test_ in the prefix: gfy_sk_test_… and gfy_pk_test_<shop>_…. It is completely separate from your live shops and has every feature without a licence (plan test). GET /v1/me and every shop show livemode: false, and so do webhook events. Shops created with a test key are test shops again.
Linking licences only works in live mode (403 live_key_required). Check livemode in your code before you take events into your production system.
Request-Id
Every response carries a Request-Id header (req_…), errors also carry the field requestId. If you send your own Request-Id (1 to 64 characters from A–Z a–z 0–9 . _ -), we use it. Quote the ID when you contact support.
Storage
We store only a hash of each key (HMAC-SHA256). After creation you never see the secret again, only a hint with the last four characters and the day it was last used.
Rotation and revocation
- Get a new key:
POST …/keys/{key}/rotate. The old one keeps working forgraceSeconds(default 1 day, at most 7). - Roll out the new key.
- If a key leaked, revoke it at once:
DELETE …/keys/{key}. You cannot revoke the last active secret key (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()Plan and licence
Without a licence the shop runs on Free. Link a Pro or Agency key (GRFY-…) from your Garanify account with PUT …/license; it is activated for the first domain of the shop. Limits per plan in 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()