DataRoles: reusable record security for multi-tenant SaaS

How DataRoles fits into BuildWithHQ

BuildWithHQ DataRoles provide one authorization model for first-class modules, custom modules, pages, APIs, AI operations, exports, billing actions, and isolated extensions. Users may hold multiple active roles, and a record may be shared with multiple roles without duplicating the data. Access resolves as a filter rather than a gate: unentitled records are absent from the result set, not refused.

Platform relationship: This capability uses the same tenant, record, permission, workflow, logging, AI, and extension architecture as the rest of BuildWithHQ.

Core architecture

Tenant boundary

Every DataRole belongs to one customer account. Role membership and record sharing are resolved inside the same tenant boundary.

User membership

A user can hold several active DataRoles, allowing functional, geographic, financial, and supervisory responsibilities to be combined.

Record sharing

The universal RecordId can be shared with one or more roles, allowing contacts, conversations, tasks, files, calendar events, AI insights, and custom records to inherit the same security context.

Permission flags

Read, AI-read, export, billing, trust-record, and disbursement-approval permissions are evaluated independently.

Permission keys

Named permission keys extend the model with vertical capabilities such as workflow publishing, contact merging, or encrypted-field reveal.

Authorization resolution

DataRoles resolve as a filter, not a gate. The platform does not fetch a record and then decide whether to refuse it. It derives the set of records the user is entitled to and every read path draws from that set, so a record the user has no role on is simply not present. There is nothing to reject, because there was never a candidate to reject.

1. Resolve identity

The tenant user and active account come from the session. Identity is never taken from a request body or query string.

2. Derive the entitled set

Tenant boundary, active role memberships, record-to-role assignments, and location scope are resolved together into one set of RecordIds.

3. Read through the set

Every query for tenant data joins against that set. Lists, searches, detail views, exports, and AI retrieval all draw from the same resolved envelope.

4. Evaluate the operation flag

Read, AI-read, export, and named permission keys are separate flags on the same row, so a record can be readable and non-exportable at once.

5. Audit the privileged operations

Ordinary reads of the entitled set are routine. Encrypted-field reveals, exports, AI retrievals, financial actions, and extension calls are recorded as discrete events.

What a user actually experiences

Pages load with what that person can see. A list shows their records; a search returns their matches; a related-records panel shows the links they are entitled to. No error appears, no permission banner is shown, and no empty placeholder marks the position of something withheld — because nothing was withheld at render time. The set the page was built from never contained it.

This is a stronger property than refusing access, not a weaker one. A system that fetches a record and then returns an error has confirmed the record exists, and has usually confirmed something about it — its identifier, its module, sometimes its owner. Filtering at the source leaks nothing: an unentitled record and a non-existent record are indistinguishable from outside.

Where refusal does happen

There is one place the model is a gate rather than a filter, and it is deliberate. Revealing an encrypted field is an explicit, separate operation rather than part of rendering a page. It is authorized on its own, it can be refused, and both outcomes are written to the compliance log with the user, the record, the field, and the reason. Page layout can never trigger a reveal as a side effect, which is why a reveal is meaningful enough to be worth refusing and recording.

Secured AI relationship

Independent AI authority

Human read access does not automatically permit AI use. CanAiReadRecords can be narrower than CanReadRecords.

Filtered retrieval

The AI layer receives only records already allowed by the user’s tenant, role, location, and AI-read envelope.

Action enforcement

An AI suggestion does not bypass business permissions. The resulting action is checked again before execution.

Example

Healthcare-style separation

A doctor, nurse, CNA, and billing specialist can share one patient record while receiving different fields, actions, AI permissions, and financial capabilities.

Franchise operations

A regional manager can see several locations, a franchise owner can see one organization, and corporate staff can see records across the network.