Authentication and API keys

Every Data API endpoint uses a company API key. Send the key in the Authorization header on every request:

Authorization: Bearer rz_live_xxx

A console session (cookie) doesn’t work on these endpoints, and the console’s own endpoints don’t accept API keys.

Key types

Type	Format	Where	What it can do
Secret	rz_live_ + 32 characters	Only on your server	All Data API endpoints within the scopes you choose
Publishable	rz_pub_ + 32 characters	In the browser, on your site	Only calls:request: the embeddable button’s endpoints, only from allowed domains

A publishable key gets 403 publishable_key_not_allowed everywhere except the button, and cannot start a call on its own; every request needs a one-time token issued by your server. Button →

Creating a key

1. Settings → API keys → New key (admins and owners; plan: Data API or Call-me button).
2. Key type: Secret (on your server) or Public (button). For a publishable key, enter the allowed domains, one per line (https://www.example.com; no path or query; http only for localhost and *.test).
3. For a secret key, choose the permissions (scopes). At least one is required.
4. Create key. The key is shown only once: copy it right away and store it safely.

The key isn’t stored in plain text; only its SHA-256 hash and last four characters are kept. If you lose it, revoke it and create a new one. Create a separate key per system so you can revoke them individually. The list shows each key’s last used time. Your plan’s API keys limit counts active (not revoked) secret and publishable keys together.

Revoke takes effect immediately: systems using the key lose access at once.

Scopes

Scope	Endpoints it allows
ingest:catalog	PUT /api/v1/catalog/products, DELETE /api/v1/catalog/products/{item_ref}, PUT /api/v1/catalog/categories, DELETE /api/v1/catalog/categories/{kategori_id}
ingest:orders	PUT /api/v1/orders
ingest:kb	PUT /api/v1/kb/articles
ingest:carts	PUT /api/v1/sepetler, DELETE /api/v1/sepetler/{dis_id}
read:carts	GET /api/v1/sepetler
ingest:customers	PUT /api/v1/musteriler, DELETE /api/v1/musteriler/{dis_id}
read:requests	GET /api/v1/requests
calls:read	GET /api/v1/cagrilar, GET /api/v1/cagrilar/{call_id}, GET /api/v1/konular/istatistik, GET /api/v1/aramalar/{arama_id}
calls:read:transcript	transcript in the GET /api/v1/cagrilar/{call_id} response. Also covers calls:read (added to the key automatically)
calls:write	POST /api/v1/aramalar, GET /api/v1/aramalar/{arama_id}, GET /api/v1/amaclar, POST /api/v1/buton-token
webhooks	Reserved; no endpoint uses it today
calls:request	Publishable keys only; the button’s browser endpoints

GET /api/v1/me needs no scope; it returns whether the key is valid and its scopes. Use it as a connection test:

curl -s "$RZ_API/api/v1/me" -H "Authorization: Bearer $RZ_KEY"
# {"org": "firma", "key_name": "Site integration", "scopes": ["ingest:catalog", "ingest:orders"]}

Plan features

Endpoints depend on your company’s plan. Endpoints of a feature that is off return 404 not_found (as if they didn’t exist):

Endpoints	Feature needed
me, catalog/*, kb/articles, orders	none — on in every plan
requests, cagrilar	Data API
konular/istatistik	Data API + Topic analytics
aramalar, amaclar	Data API + Outbound calls
sepetler, musteriler	Data API + Carts
buton-token	Call-me button (Outbound calls must also be on)

Key security

Never put a secret key in a browser, a mobile app or a public repository. If a key leaks, revoke it at once; the Change History shows who created it, with which scopes, and when it was revoked.