Roles

View Orgs and users in the API reference

Roles are permission grants assigned to a user in an organization. A role granted on an org also applies in every org below it.

How a role check works

For each operation, OpenApp asks whether the caller holds the required role string in the resource’s organization or in any of its ancestors:

admin on that org or an ancestor satisfies every role in the list below.
platform_admin on that org or an ancestor also satisfies every role below. A few system operations need platform_admin on the root org specifically (see System roles).
Otherwise the caller needs the exact role string.

Roles are stored on the org where you assign them. A user with admin on a parent org only has that access in every sub-org without copying the role onto each child.

A scoped API key, voice key, or agent credential can only exercise roles named in its scope. The owner’s admin or platform_admin does not widen it: a key scoped to entities:set_state can use only that role, even when its owner is an admin.

Permission roles

This is the complete list of permission role strings OpenApp checks.

API keys

Role	Grants
`api_keys:create`	Create API keys and voice keys for the organization. Listing, renaming, revoking, restoring, and deleting keys is limited to the keys you own.

Audit log

Role	Grants
`audit:read`	Read the organization audit log and request historical exports.
`audit:webhooks:manage`	Manage outbound audit webhook endpoints.

Billing

Role	Grants
`billing:read`	Read plan, quota usage, and invoices.
`billing:manage`	Change plan and payment settings. On the entity-action API, a caller holding it is treated as an organization admin for policy exemptions (for example lockdown and maintenance window).

Devices

Role	Grants
`devices:create`	Create devices.
`devices:read`	Read one device.
`devices:update`	Update a device, and read credential-bearing provisioning data (for example Tasmota provisioning).
`devices:delete`	Delete, purge, or restore a device.
`devices:list`	List devices.

Entities

Role	Grants
`entities:create`	Create entities.
`entities:read`	Read one entity.
`entities:update`	Update an entity, and manage directory-listing members and site people.
`entities:set_state`	Run `switchable.*` actions (open, close, toggle) except the relay latch.
`entities:set_hold`	Set or clear an entity hold, and run `switchable.set_relay_mode`. Not implied by `entities:set_state`.
`entities:delete`	Delete, purge, or restore an entity.
`entities:list`	List entities.

Groups

Role	Grants
`groups:create`	Create a non-household group.
`groups:read`	Read a group, its members, links, and admissions.
`groups:update`	Update a group, its members, and admissions.
`groups:delete`	Delete a group.
`groups:list`	List groups linked into the organization.
`groups:share`	Offer a group to another organization.
`groups:link`	Accept an offered group into this organization.

Integrations

Role	Grants
`integrations:create`	Create integrations.
`integrations:read`	Read an integration, its invitations, and its secrets.
`integrations:update`	Update an integration, manage portals and invitations, and read provisioning status (for example Waveshare).
`integrations:delete`	Delete, purge, or restore an integration.
`integrations:list`	List integrations.
`integrations:users:list`	List users in the upstream vendor directory (for example PalGate gate users).
`integrations:users:write`	Add or remove users in the upstream vendor directory.

Organizations

Role	Grants
`orgs:create`	Reported by `GET /orgs/{id}/permissions`. Creating a sub-org is decided by `admin` on the parent, not by this role — see the note below.
`orgs:read`	Read an organization. Any role in an org also lets you read that org.
`orgs:update`	Update an organization. Moving it to another parent also needs `admin` on the destination.
`orgs:delete`	Delete an organization.
`orgs:list`	List organizations below the one where you hold it.

Policies

Role	Grants
`policies:create`	Create org, integration, and device policies.
`policies:read`	Reported by `GET /orgs/{id}/permissions`. Reading policies uses `policies:list`.
`policies:update`	Update policies, set the org timezone, and vote on pending policy approvals.
`policies:delete`	Delete policies.
`policies:list`	List policies, effective policies, the org timezone, and pending approvals.

OpenApp Scripting

Role	Grants
`execute`	Submit OpenApp Scripting executions (`POST /api/v1/scripting/executions`, `openapp scripting`, SDK `client.scripting`). It grants nothing inside the script: every operation a script performs needs its own role.

Users

Role	Grants
`users:create`	Create users in the organization.
`users:read`	Read a user who belongs to the organization.
`users:update`	Update such a user.
`users:delete`	Delete such a user.
`users:list`	List users in the organization.

Zones

Role	Grants
`zones:create`	Create zones.
`zones:read`	Read a zone.
`zones:update`	Update a zone.
`zones:delete`	Delete a zone.
`zones:list`	List zones.

System roles

These are not implied by any users:* role. The two system:* roles take effect only on the root org: an admin of any other org does not hold them, and GET /orgs/{id}/permissions reports them only for the root org.

Role	Grants
`system:list_kratos_identities`	List sign-in identities across the deployment.
`system:delete_kratos_identities`	Delete a sign-in identity that is still pending registration.
`platform_admin`	Everything `admin` grants. On the root org it also allows creating an org with an explicit id, creating users without assigning roles, managing any user, merging accounts, and other deployment-wide operations.

Site roles

Site (Virtual Access) roles are granted per integration and have the form:

virtual_access:integration:{integration_id}:{role}

`{role}`	Who holds it
`admin`	A site administrator, or a listing admin.
`resident`	A person who lives or works at the site.
`member`	A listing member added through directory listings.
`technician`	Maintenance staff. Matches `technician` in who may invite and maintenance window policies.

OpenApp writes these roles when you add someone to a site (POST /integrations/{id}/people, or a site grant on an org invitation, which accepts admin, resident, or technician) or to a listing (which accepts admin or member). Assign them through those routes, not by hand. A site role alone grants no permission role above; what it lets someone open comes from listing membership and site access rules.

API keys — scoped credentials
Policy catalog — limits layered on top of roles
OpenApp Scripting