Operational apps
Operational apps: permissions and environments
Roles, capabilities and scope with a per-store example, organization admins, QA and production environments, promoting and suspending an app.
Updated: 2026-11-17
In this guide
The model in four concepts
- Capability: a name you choose for something that can be done, such as
returns.decide. Actions, file slots and forms declare which capability they require. - Role: a named set of capabilities, owned by the app.
- Assignment: gives a role to a user (
userId) or to every user with an organization role (orgRole, for examplememberoreditor). - Scope: limits an assignment to certain values of a dimension, such as a list of stores.
Everything is checked on the server. The dashboard only hides what the user cannot do.
Who can open the app
visibility has two values:
organization: any organization member with access to Operational apps can open it. What they can do inside depends on their assignments.assigned: only users with an assignment and organization admins can open it. Everyone else does not see it in the list.
An app without accessControl is open to the whole organization and its actions cannot require capabilities.
A per-store example
The returns app from the quickstart has a storeId field on every record. This block limits each person to their stores:
{
"accessControl": {
"visibility": "assigned",
"scopeFields": { "store": "storeId" },
"scopeValues": {
"store": [
{ "value": "store-01", "label": "Downtown" },
{ "value": "store-02", "label": "North" }
]
},
"roles": {
"agent": { "label": "Agent", "capabilities": ["returns.read", "returns.create", "returns.attach"] },
"supervisor": { "label": "Supervisor", "capabilities": ["returns.read", "returns.create", "returns.attach", "returns.decide"] },
"auditor": { "label": "Auditor", "capabilities": ["returns.read"] }
},
"assignments": [
{ "userId": "user_41", "role": "agent", "scope": { "store": ["store-01"] } },
{ "userId": "user_52", "role": "supervisor", "scope": { "store": ["store-01", "store-02"] } },
{ "orgRole": "editor", "role": "auditor" }
]
}
}
scopeFields connects the store dimension to the storeId field of the records. With that:
user_41, Downtown agent: sees only the returns ofstore-01. They can create returns for that store and attach receipts. If they try to create one forstore-02, they get a 403. They do not see the Approve or Reject buttons, and calling the action through the API returns a 403.user_52, supervisor of two stores: sees and decides returns ofstore-01andstore-02.- Users with the
editororganization role: are auditors without scope, so they read the returns of every store. They cannot decide or see receipts, because the slot requiresreturns.attach. - Any other user: cannot open the app.
The app each user receives includes their permission already resolved. For user_41:
{
"grant": {
"canOpen": true,
"capabilities": {
"returns.read": { "store": ["store-01"] },
"returns.create": { "store": ["store-01"] },
"returns.attach": { "store": ["store-01"] }
}
}
}
A capability with the value null has no scope restriction.
Rules worth knowing
- Reading is also a capability. With
scopeFieldsdeclared, a user reads a record if it falls within the scope of at least one of their capabilities. That is whyreturns.readexists even though no action uses it. - Without
scopeFields, there is no per-record scope. Everyone who opens the app reads all its records. - Assignments add up. If a user has two assignments, they get the capabilities of both. Values of the same dimension are merged.
- Open wins. If one assignment gives a capability without scope and another limits it, the capability stays unlimited.
- An assignment without
scopedoes not restrict. Neither does a dimension missing fromscope. - Collection actions and app slots: there is no record to measure scope against, so having the capability in any scope is enough.
- Record slots: apply the slot's capability within the record's scope.
- Datasets: have no scope. Everyone who can open the app reads them.
- Assignments are private. Only those who manage definitions receive the list of assignments; other users receive only their
grant.
Organization admins
An organization admin has every capability of the app, without scope, with no assignment needed. That way an app can never lock out its own organization.
Managing definitions is something else: the admin and editor roles can install packages, export them and see draft apps. An editor gets no capabilities from that; to operate the app they need an assignment, like any user.
Environments
An app is installed in an organization and an environment. QA and production are separate spaces: each has its own record types, app definition, records, files, datasets, settings and assignments. Nothing is shared.
- In the dashboard you work on the selected environment.
- In the API you choose the environment with the
x-qac-environmentheader. Without the header the organization's default environment is used. A key that does not exist is rejected with 400. - A flow runs in the environment where the action happened. The envelope carries
environmentand the Python client writes to that same environment.
Promoting an app from QA to production
Promoting is copying data: you install the same package in the other environment.
If you keep the package in your repository, install the same file in each environment:
jq -n --slurpfile pkg returns.package.json '{package: $pkg[0]}' |
curl -X POST "$QAC_API/operational-apps/install" \
-H "Authorization: Bearer $QAC_TOKEN" \
-H "x-qac-environment: prod" \
-H "Content-Type: application/json" \
-d @-
If the good version is the one installed in QA, export it and install it in production:
curl "$QAC_API/operational-apps/returns/package" \
-H "Authorization: Bearer $QAC_TOKEN" \
-H "x-qac-environment: qa" |
jq '{package: .package}' |
curl -X POST "$QAC_API/operational-apps/install" \
-H "Authorization: Bearer $QAC_TOKEN" \
-H "x-qac-environment: prod" \
-H "Content-Type: application/json" \
-d @-
The export returns the package as installed, including that environment's settings and assignments. What changes between environments goes in overrides, next to package in the install body:
{
"overrides": {
"settings": { "refundProvider": "live" },
"accessControl": {
"assignments": [
{ "userId": "user_52", "role": "supervisor", "scope": { "store": ["store-01", "store-02"] } }
]
}
}
}
settingsis merged over the package settings: you only change the keys you send.accessControl.assignmentsreplaces the whole list.accessControl.scopeValuesreplaces the scope values, for example when the QA stores are not the production ones.- No other part can be adjusted at install time. If you need a different structure, it is a different package.
Installing is repeatable. Reinstalling the same document with the same overrides changes nothing, and the response tells you what was created, what was updated and what stayed the same.
Records are not promoted. QA data stays in QA.
Suspending an app
To stop an app, install the package with "status": "suspended" in app. To resume it, install it again with "status": "published".
While it is suspended:
- Users stop seeing it and its records stop being available to them.
- Nobody can run actions, upload files or read datasets: the API responds 409.
- Flows that were queued do not start.
- Records, history and files are kept intact.
draft is for the opposite: preparing an app users should not see yet. Only those who manage definitions can open and test it.