Authentication

The Qariyb API uses key-based authentication. Server-to-server requests to the REST API are authenticated with your secret key; browser widgets and Qariyb Elements are authenticated with your publishable key.

Every integration is issued a matched pair of keys from a single organization:

• Publishable key (pk_live_…) — safe to embed in the browser. Used by widgets and Qariyb Elements via the X-Widget-Key header.
• Secret key (sk_live_…) — server-side only, keep it private. Used by the REST API via the Authorization: Bearer header.

Keys are always live. Test mode was removed: there are no pk_test_ / sk_test_ variants, and a key using those prefixes is rejected on format before any lookup.

Which key, which API

The key you hold decides which API you are calling. They are two separate surfaces, not two ways into the same one.

Building a custom checkout on your own website? Either surface can do it, and the choice is simply where your code runs:

• No backend, or you want the browser to talk to Qariyb directly — use the publishable key and the public endpoints. This is the same surface Qariyb Elements uses, so you get the Stripe.js flow without running a server. See Public checkout.
• You already have a backend and want checkout to run there — use the secret key and the REST endpoints, and have your own frontend talk to your server rather than to Qariyb. See Checkout.

Do not mix them. A publishable key sent to a REST endpoint is rejected with 607, and a secret key sent from a browser is a credential leak, not a configuration mistake — it is not scoped to one event or one action, so anyone who reads it can act as your whole organization.

Secret key authentication

Server-to-server requests to the REST API (/api/v1/*) must include your secret key in the Authorization header with the Bearer prefix:

curl https://api.qariyb.com/api/v1/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Accept: application/json"

Alternatively, you may pass the secret key in the X-Secret-Key header:

curl https://api.qariyb.com/api/v1/events \
  -H "X-Secret-Key: sk_live_..." \
  -H "Accept: application/json"

Creating API keys

API keys are created through the Qariyb developer dashboard:

1. Log in to your Qariyb organizer account
2. Navigate to Settings → Developer → API keys
3. Click Create API Key
4. Give the key a descriptive name
5. Copy and securely store the secret key

Creating a key issues a matched pair: a publishable key (pk_live_…) and a secret key (sk_live_…). The secret key is displayed once at creation and cannot be revealed later — Qariyb stores only a hash. If you lose it, rotate the key to generate a new secret.

Key security

Best practices for key security:

• Store secret keys in environment variables
• Never expose the secret key in browser or mobile client code
• Rotate keys periodically
• Rotate immediately if a secret key may have been exposed

Rate limiting

Rate limits are per API key, counted per minute. Each key carries its own rate_limit_per_minute value, which defaults to 120:

Checkout and RSVP writes are deliberately budgeted at half the key's read limit, because they create carts and orders rather than just reading. Raising a key's rate_limit_per_minute raises both proportionally.

Rate limit headers are included in throttled responses:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 98

On a 429 the response also carries Retry-After (seconds) and X-RateLimit-Reset (Unix timestamp).

When you exceed the rate limit, you will receive a 429 Too Many Requests response:

{
  "success": false,
  "code": 206,
  "message": "Too many requests. Please try again later."
}

Widget key authentication

The public widget API (/api/v1/public/*) uses the publishable key. It is designed for embedding checkout widgets on third-party websites and does not require user authentication.

Include your publishable key in the X-Widget-Key header:

curl https://api.qariyb.com/api/v1/public/events/01HWX9KPQR \
  -H "X-Widget-Key: pk_live_..." \
  -H "Accept: application/json"

You can also pass it as a widget_key query parameter when a header cannot be set:

curl "https://api.qariyb.com/api/v1/public/events/01HWX9KPQR?widget_key=pk_live_..."

The publishable key is managed alongside the secret key through the Developer dashboard under API keys. Each integration has:

• Publishable key (pk_live_*) — safe for client-side use
• Secret key (sk_live_*) — for the server-side REST API only
• Domain restrictions — optionally restrict which domains can use the publishable key

Widget API rate limits: 120 requests/minute for reads, 60 requests/minute for checkout and RSVP writes — both at the key's default. Unlike the REST API, the widget limiters also key on the caller's IP address, so one busy visitor cannot exhaust the whole organization's budget.

Key permissions

API keys are scoped to the organization that created them. This means:

• A key can only access events owned or managed by that organization
• The secret key grants full REST API access for that organization
• The publishable key is limited to public read and checkout/RSVP endpoints