Data Model

This page describes how data is attached to tenants and sites, and introduces the entities you will meet most often through the API. The API returns plain JSON objects: the entity names below describe concepts, not type names you will see in responses.

Multi-tenancy

Inklura is multi-tenant, and the scope is carried by the data itself:

  • tenantId (uuid) is present on every record that belongs to a tenant.
  • siteId (uuid) is also present when a record belongs to a specific site.

A tenant has a name, a unique short code (for example acme) and a status. It owns one or more sites, each with a name, an optional slug, a status, and free-form data. A site's status is ACTIVE, INACTIVE or PENDING; a tenant's can also be SUSPENDED. Both start as PENDING.

On every request, the API resolves a tenant/site scope (see Sessions & Tokens) and only reads or writes records within that scope. Your token names your account's home tenant and site, but the scope is not fixed in it: it is resolved on each request, then checked against your account's access. See tenancy.

Main entities

The following entities are the ones you will most often work with through the API.

Entity What it is
Tenant The tenant: name, unique code (e.g. acme), status.
Site A site owned by a tenant: name, slug, status, data.
Membership Gives a user a role (OWNER or MEMBER) in a tenant, optionally limited to one site.
User A user: email, home tenantId, optional siteId.
Role / Permission Roles and permissions of the form resource:action (for example products:read).
Product Catalog products, with their available stock.
Order Orders, their line items, and fulfillment.
Stock action The stock movement ledger.
Vendor / Supplier order Vendors and the orders placed with them.
Invoice Invoices, quotes, and credit notes.
Subscription Subscriptions.
Campaign Marketing campaigns.
Site domain / Site settings A site's domains and settings.
Feed API key A scoped key for a site's content feeds.

Feed API keys

A site's content feeds can authenticate with their own scoped keys instead of a user session. A feed key:

  • starts with the feed_ prefix. The full key is returned only once, on creation or regeneration; afterwards only its prefix (keyPrefix) can be read;
  • belongs to a tenant and a site. A site must therefore be selected to create one, and its name (name, at most 100 characters) is unique per (tenant, site);
  • carries an hourly request limit (rateLimit, 0 to 10000, 1,000 by default, 0 for unlimited);
  • accepts an optional allowedIps allowlist: comma-separated IPv4 addresses, IPv4 CIDR ranges or IPv6 addresses (IPv6 ranges are not accepted). An invalid entry is rejected with BAD_REQUEST; an empty value removes the restriction;
  • can have an expiresAt date and can be deactivated without being deleted;
  • carries a set of permissions among full_content, unlimited_requests and custom_cache (["full_content"] by default).

Keys are managed through the feedApiKeys tRPC router:

Procedure Type What it does
list query Keys of the current tenant and site (without the full key).
get query One key, by id.
create mutation Creates a key and returns the full key in key.
update mutation Changes name, description, permissions, limit, allowed IPs, expiry or isActive.
regenerate mutation Replaces the key (the old one stops working) and returns the new one in key.
toggleActive mutation Activates or deactivates a key.
delete mutation Deletes a key.
getStats query Number of keys, active keys, expired keys, total requests, keys used in the last 24 h.

Reads require the feed:read and cms:read permissions, writes feed:write and cms:write.

The embeddable live-chat widget also uses its own keys, separate from feed keys.

These keys are the exception; the general API uses sessions and Bearer JWTs (see Authentication).