Skip to content
All technical docs Bricks technical documentation

The data API & its permissions

How the Bricks REST data API selects a tenant and enforces access — the row-level permission model behind every table, and the load-bearing difference between a tenant API key and an integrator API key.

The data API & its permissions

Bricks Technical Documentation

How the Bricks REST data API selects a tenant and enforces access — the row-level permission model behind every table, and the load-bearing difference between a tenant API key and an integrator API key.


Bricks exposes tenant data over a standard REST API. Any HTTP client can read and write a tenant's tables — but what it can read and write is decided in the database itself, by row-level security, not by application code that could be bypassed. This page explains the request shape, the permission model behind it, and the one distinction that most affects security: tenant keys versus integrator keys.

Two surfaces, kept apart

There are two ways into tenant data, and they enforce access differently:

  • The data API — /rest/v1/{table}. The public, customer-facing REST surface. Row-level security (RLS) is the enforcement boundary. Every row a request sees or changes is decided by database policies.
  • The management API — /v2/…. The administrative surface used by the Bricks app and by integrators for schema and table management. Its endpoints check the caller's role (covered at the end).

Request shape

The URL carries only the table name. The tenant is chosen by header, never by the path or a subdomain.

GET https://bricks-softwares.com/rest/v1/products
Header Purpose
X-API-Key: bricks_… Your secret Bricks key (or Authorization: Bearer bricks_…)
Accept-Profile: tenant_acme Selects the tenant schema for reads
Content-Profile: tenant_acme Selects the tenant schema for writes (POST / PATCH / DELETE)

The tenant schema you name in the profile header must exist and be active; naming a schema your key is not entitled to is refused at the database boundary. Omitting the profile header falls back to the public schema, where your tenant's tables do not exist — so the request fails with "relation does not exist." Always send the profile header.

Filtering, ordering and pagination follow standard PostgREST query syntax — see Filtering & pagination and CRUD operations in the API reference.

What a request actually does

mermaid diagram

The permission model

Access to tenant rows is decided by three layers of database rules, all generated from a permission matrix rather than hand-written per table. When a request touches a table, the policies combine to answer "may this caller do this to this row?"

  • Role permissions — full-table create/read/update/delete grants keyed on the caller's tenant role. A "manager" role might read and write orders; a "viewer" role only reads them.
  • Row ownership — per-user ownership rules that narrow access to specific rows. Ownership can be direct (a column equals the user's id), through a junction (membership via a link table), or through a foreign key (inherited from a parent record). Each ownership rule carries its own select / insert / update / delete flags.
  • Anonymous read flags — explicit per-table opt-in for genuinely public data. Nothing is public by default.

There is no "signed-in users can read everything" rule. Access is granted explicitly or it does not exist.

Tenant keys versus integrator keys

Two kinds of key can reach tenant data, and they authorize on completely different principles. Choosing the wrong one is the most common way to over-expose data.

Tenant key

A tenant key is bound to exactly one tenant. It is a server-side credential that an administrator creates for a backend or integration they run, and it must stay secret. It grants access to its own tenant only, and never at an administrative level. It is not a person; it carries no user identity.

A published app never receives a key. It is a static bundle running in a browser, so anything placed in it is public; an app reaches its data as the signed-in person, under that person's role and row-ownership rules.

Integrator key

An integrator key is a personal key tied to the user who created it. This is the subtle, load-bearing part:

Tenant reads authorize on the key owner's membership — not on the key itself.

An integrator key can read every tenant its owner is a member of. Treat it like that person's own access.

mermaid diagram

Building a safe external integrator key

To give an outside integration read access to one tenant and nothing else, scope it through a dedicated, minimal user rather than an existing privileged account:

  1. Create a dedicated service user for the integration.
  2. Grant that user the lowest read-capable role on only the target tenant — no membership anywhere else.
  3. Create the integrator key owned by that user.

Then prove the scoping before shipping: the key should return 200 against the target tenant and 403 against any other tenant. If it can read a second tenant, the owning user has a membership it should not have.

Management endpoints require an organisation admin

The /v2/tenants/:tenantId/tables/… endpoints — reading and writing records, managing columns, changing table settings, dropping tables or columns — require org_admin on that tenant. A member, a manager or a custom role cannot use them. Only listing table names (not their rows) is open to any member.

Common pitfalls

  • Missing profile header → the request resolves against the public schema and fails with "relation does not exist." Send Accept-Profile (and Content-Profile for writes).
  • Wrong-tenant key → naming a schema your key is not entitled to is refused at the database boundary.
  • Platform-scoped keys carry no tenant-data access by design — they are for platform operations, not for reading tenant tables.
  • Never ship an integrator key minted under an admin account. It inherits that account's memberships. Use a dedicated minimal user and prove 200-here / 403-elsewhere.

This page describes shipped behavior. For request-level detail — authentication headers, CRUD verbs, filtering, schema discovery — see the API reference. For calling tenant functions and building automations, see The RPC API & workflows.