Public API Overview: Keys, Tenants & Rate Limits

Overview

OrbioCloud exposes read and capture APIs that let your storefront (OrbioShop) and website (OrbioSite) pull live data and submit form entries. These are public, key-authenticated REST endpoints intended to be called from your site's front end or server.

• Site & forms (OrbioSite, leads, newsletter): https://app.orbiocloud.com/api/public/...

• Storefront (OrbioShop products, cart, checkout): https://{your-subdomain}.shop.orbiocloud.com/api/public/shop/{your-subdomain}/...

Authentication

Every request must include your API key in the X-API-Key header. Keys are created and managed in your dashboard (Website hub -> API Keys, or your shop settings). A read key is enough to fetch content and products; submitting orders needs a key with the orders permission.

curl https://app.orbiocloud.com/api/public/website?subdomain=your-subdomain&section=all \
  -H 'X-API-Key: your_api_key'

Identifying your tenant

Your tenant is identified by your subdomain. It is resolved in one of two ways:

• Automatically from the host when the API is served on your own domain (an x-tenant-subdomain header is set for you).

• Via a ?subdomain=your-subdomain query parameter for direct calls. Required when you call app.orbiocloud.com directly.

The key you send must belong to the tenant identified by the subdomain.

Allowed origins (CORS)

A key can be restricted to specific origins. Browser (cross-origin) requests from an origin that is not on the key's allowlist are blocked, while server-to-server calls still work. Add your site's origin(s) to the key if you call it from the browser.

Rate limits

Limits are applied per API key on a sliding window. When you exceed the limit you receive an HTTP 429 with a RATE_LIMITED error. Design for it:

• Cache responses on your side. Product and content responses are also cached briefly server-side (about 60 seconds).

• Use separate keys for development and production so test traffic does not consume your live quota.

• Need a higher limit? Your key's per-minute allowance is configurable - request an increase through your dashboard or support.

HTTP 429
{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Please try again later." } }

Error shapes

Storefront endpoints return errors as { success: false, error: { code, message } }. The site/leads/newsletter endpoints return { error: "message" }. Common statuses: 400 (validation), 401 (missing/invalid key), 403 (origin or permission), 429 (rate limited).