Permissions

Permissions are a declaration of an action that can be executed on a resource. They describe the intrinsic capabilities or operations available on that resource (e.g. read a datastream, or update a station), independent of any specific user.

Permissions granted to a user (also called privileges) can be found in up to three locations in Dendra Release 3.

Location	Description	Resource Domain	Example
Access Token	Permissions granted to a user based on their assigned roles in the IAM. Listed in the permissions claim in the access token.	Platform and system resources	create:unit update:vocabulary
Resource	Permissions granted to a user based on their assigned role in an organization. Listed in the resource’s effective_rights field.	Organization (Datastreams, Stations)	read:datastream update:station
Header Claim	Permissions granted for service-to-service API calls. Claimed when using a system API key.	Internal services	read:deleted:organization create:job

Note

Permissions to access datasets (metadata or data) are separate from permissions required to act upon a resource. Dataset access is determined by a combination of user’s role in an organization and the resolved access level on a resource. If you cannot view something (like a datastream or station), then you cannot act upon it either. See Access Level for more details, and Dataset Access for how datapoint access becomes permissions.

Organization Resources

Organization resources (resources that belong to an organization) break this down even further to the individual resource level.

Resource	Field	Description	Example
Organization	effective_rights field of the Organization resource.	Statements of what you can do with or within the organization.	create:datastream update:organization
Datastream	effective_rights field of the Datastream resource.	Statements of what you can do with the datastream.	read:datastream update:datastream
Site	effective_rights field of the Site resource.	Statements of what you can do with the site.	read:site:geo.exact update:site
Station	effective_rights field of the Station resource.	Statements of what you can do with the station.	read:station:file.private update:station
Membership	effective_rights field of the Membership resource.	Statements of what you can do with the membership.	read:membership:email update:membership

Organization Role Policies

Based on a user’s role in an organization and the resource they are acting on, a role policy is selected to provide the list of permissions that the user has for that resource.

Below are the current role policies in the system by resource. These are subject to change.

Organization

Role	Permissions
Member	read:alert read:file_import_manifest read:integration_config read:monitoring_rule read:organization:file.private read:notification_delivery read:notification_preference update:notification_preference
Curator	create:datastream create:file_import_manifest create:integration_config create:monitoring_rule create:org_key create:site create:station delete:org_key discover:table query:table read:alert read:file_import_manifest read:integration_checkpoints read:integration_config read:integration_config:settings read:integration_pipeline read:integration_runtime read:integration_storage_target read:monitoring_rule read:org_key read:organization:file.private read:organization_notification_config read:notification_delivery read:notification_preference read:table_info rotate:org_key update:alert update:file_import_manifest update:integration_config update:monitoring_rule update:organization update:organization_notification_config update:notification_preference update:table_info
Admin	create:datastream create:file_import_manifest create:integration_config create:membership create:monitoring_rule create:notification_delivery create:org_key create:site create:station delete:integration_config delete:monitoring_rule delete:org_key delete:organization discover:table query:table read:alert read:file_import_manifest read:integration_checkpoints read:integration_config read:integration_config:settings read:integration_pipeline read:integration_runtime read:integration_storage_target read:monitoring_rule read:org_key read:organization:file.private read:organization_notification_config read:notification_delivery read:notification_preference read:table_info report:alert report:integration_runtime restart:integration_runtime retire:integration_config rotate:org_key set:organization:feature_flags update:alert update:file_import_manifest update:integration_checkpoints update:integration_config update:monitoring_rule update:notification_delivery update:organization update:organization_notification_config update:notification_preference update:table_info

Datastream

Role	Permissions
Member	read:datastream:file.private
Curator	read:datastream:file.private update:datastream
Admin	delete:datastream read:datastream:file.private update:datastream

Permissions to chart or download a datastream’s datapoints (chart:datastream and download:datastream) are added to these lists from the datastream’s access level. See Dataset Access.

Site

Role	Permissions
Member	read:site:file.private read:site:geo.exact
Curator	read:site:file.private read:site:geo.exact update:site
Admin	delete:site read:site:file.private read:site:geo.exact update:site

Station

Role	Permissions
Member	read:station:file.private
Curator	read:station:file.private update:station
Admin	delete:station read:station:file.private set:station:feature_flags update:station

Membership

Role	Permissions
Member	None (default policy when acting on another user’s membership)
Curator	read:membership:email read:membership:join_message read:membership:note update:membership update:membership:is_pending update:membership:is_revoked update:membership:note
Admin	delete:membership read:membership:email read:membership:join_message read:membership:note update:membership update:membership:is_pending update:membership:is_revoked update:membership:email update:membership:name update:membership:note update:membership:role

Note

For Membership, the table reflects the default role policies (permissions when acting on another user’s membership). When a user reads their own membership, or when a user has organization-admin privileges, a different effective policy is provided.

Dataset Access: Chart and Download

Seeing a datastream (its metadata) is separate from reading its datapoints. Two permissions control the datapoints:

Permission	Allows
chart:datastream	A reduced set of datapoints for plotting.
download:datastream	Every recorded datapoint. Includes chart:datastream.

These are not in the access token. They are computed each time a datastream is read and listed in the datastream’s effective_rights, from the datastream’s resolved access level and the caller’s role in the datastream’s organization.

Caller	Access level used
Guest, or a user who is not a member	The datastream’s resolved public level.
Member	The datastream’s resolved member level.
Curator or Admin	Always Download.

Resolved access level	Permissions added to effective_rights
Restricted, Metadata	None.
Chart	chart:datastream
Download	chart:datastream download:datastream

Note

The platform admin:organization permission swaps the management role policies only. It does not grant download:datastream. A system admin who is not a member gets the public level for datapoints. Likewise, finding a datastream in the Data Explorer does not grant either permission. Explore applies the metadata bar only.

What Each Permission Opens

Operation	Requires	Returns
ChartSeries	chart:datastream or download:datastream	The reduced set (below).
ListDatapoints, StreamDatapoints	download:datastream	The recorded datapoints, row by row.

A caller with only chart:datastream can use ChartSeries and is rejected by List and Stream. A caller with download:datastream can use any of them. Raw table records (ListRecords, StreamRecords) are a separate, organization-level permission (query:table, Curator and Admin) and do not depend on either.

The Reduced Set

ChartSeries streams columns, not datapoints. The server estimates the sample interval, splits the requested window into time bins, and for each bin returns the recorded first, last, lowest, and highest values. These are readings that were recorded, not averages or interpolated values, so peaks and dips survive.

• A bin starts at eight sample intervals wide, so a column is never a single reading unless the data has a gap there.
• A response never has more than 8192 columns. A longer window uses wider bins, rounded to a convenient duration (for example 15 minutes, 1 hour, or 1 day).
• gap_before marks a column that follows a gap wider than the bin.
• Only integer and double output fields can be charted.
• The columns are the same for a chart:datastream caller and a download:datastream caller. There is no fuller payload for download. The Main App reads effective_rights first and uses List or Stream for download-level series, so the chart plots every reading.

Note

The server still scans the whole window to build the reduced set. A smaller response is not a cheaper read.

Access Token Permissions

Permissions in the access token are granted by IAM roles and listed in the permissions claim. Below are the available permissions by resource. These are subject to change.

Resource	Permissions
Agent ***	use:agent
Auth	acquire:v2token create:user_key delete:user_key read:user_key provision:user
Company	create:company delete:company read:company:file.private update:company
Thing type	create:thing_type delete:thing_type read:thing_type:file.private update:thing_type
Group	create:group delete:group read:group:file.private update:group
Scheme	create:scheme delete:scheme update:scheme
Unit	create:unit delete:unit update:scheme
Vocabulary	create:vocabulary delete:vocabulary update:vocabulary
Table info	create:table_info delete:table_info update:table_info update:table_info.details update:table_info.fields update:table_info.shard_configs
Organization	create:organization
Membership	request:membership
Integration	list:integration_job_registrations
Notification template	create:notification_template delete:notification_template read:notification_template update:notification_template
Notification delivery **	create:notification_delivery read:notification_delivery update:notification_delivery
Notification preference *	read:notification_preference update:notification_preference
User notification config *	read:user_notification_config update:user_notification_config
File info	update:file_info.details
Job	cancel:job create:job delete:job read:job read:worker
Platform	admin:organization read:deleted:integration_config read:deleted:organization set:id

* A user can read and update their own notification preference and contact config without these permissions.

** Needed only for requests that are not scoped to an organization. When a request names an organization, the organization permission of the same name (see Organization) applies instead.

*** Session tokens only. use:agent is removed when a user API key (den_ak_user) is validated, so a stored key cannot script the agent. That removal does not apply to organization API keys.

System API Key Permissions

Internal services authenticate to one another with system API keys. Each request must explicitly claim the permissions for that call.

Reading soft-deleted records (example)

To facilitate orchestration teardown when a resource is deleted, a system API key can claim the read:deleted:{entity} permission to read a soft-deleted record.

Permission	Get call
read:deleted:organization	GetOrganization
read:deleted:integration_config	GetIntegrationConfig

Resolving Permissions

Permissions are assigned specifically at each level and are mutually exclusive across locations. You can therefore check a single location. If needed, permissions can be resolved in this order:

1. Check the effective_rights field of the resource itself.
2. Check the effective_rights field of the resource’s Organization resource (if applicable).
3. Check the permissions claim in the access token.