Skip to main content
Version: v5.3

Permissions

Permissions​

The Application Ontology Service controls access at two levels:

  • Ontology permissions control the ontology and everything that defines it: classes, relationships, rules, constraints, actions, collection mappings, state machines, and class MCP configurations.
  • Class permissions control the individuals of a class and their relationships.

The two levels are separate. An ontology permission doesn't give access to individuals, and a class permission doesn't let you change the class definition. A user who needs both needs a grant at each level.

The Passport Service stores every grant. You grant permissions to a user, a user group, or a permission profile. Access is denied by default: without a matching grant, a call returns 403. A grant of * on *:*:* or aosvc:*:* covers every action on every ontology and class.

A permission profile can name a specific ontology, class, or state machine event, such as aosvc:ontology:{ontologyId}. Before the Passport Service saves the profile, it asks the Application Ontology Service whether the resource exists in the profile's namespace. If the resource doesn't exist there, the Passport Service rejects the profile.

Ontology permissions​

An ontology permission is a grant on the IRN aosvc:ontology:{ontologyId}. Its actions are READ, CREATE, EDIT, DELETE, SHARE, and * for all actions.

When you create an ontology, you get all permissions on it. To share it with others, you need SHARE.

Note: For more information, refer to the Grant ontology permissions Rest API section.

Class permissions​

A class permission is a grant on the IRN aosvc:ontologyclass:{classId}. Its actions are INDIVIDUALS_READ, INDIVIDUALS_CREATE, INDIVIDUALS_EDIT, INDIVIDUALS_DELETE, INDIVIDUALS_SHARE, and INDIVIDUALS_* for all actions.

Class permissions follow the class hierarchy. A grant on a class covers the individuals of the class and all its subclasses. A grant doesn't reach a parent class or a sibling class. For example, a grant on Equipment covers Pump and Valve, but a grant on Pump doesn't cover Valve or Equipment.

The class is the unit of access. You can't grant access to single individuals or single properties. To give access to a subset of individuals, model the subset as a subclass and grant on it.

A class-level READ, CREATE, EDIT, or DELETE grant also satisfies the matching INDIVIDUALS_* action. Use the INDIVIDUALS_* actions for new grants.

Note: For more information, refer to the Create or update permissions Rest API section.

Exact-match actions​

Actions match exactly. One action doesn't imply another. For example, EDIT doesn't include READ, so grant both if a user needs both.

Some calls need more than one action, because the service reads data as you before it writes:

  • To update or delete an individual, you also need INDIVIDUALS_READ.
  • To add, replace, or remove relationships, you need INDIVIDUALS_EDIT and INDIVIDUALS_READ.
  • To remove a relationship, the Item Service also checks that you have DELETE permission on the relationship record.

Item Service permissions​

The individuals of a class are stored as items in an Item Service collection. The Item Service checks your token on every call the Application Ontology Service makes for you. So the Application Ontology Service also applies each class grant to the collections that store the individuals of the class and its subclasses. Each Item Service grant is limited to the individuals of those classes, even when several classes share one collection.

The class actions become Item Service actions:

Class actionItem Service action
INDIVIDUALS_READREAD
INDIVIDUALS_CREATECREATE
INDIVIDUALS_EDITEDIT
INDIVIDUALS_DELETEDELETE
INDIVIDUALS_SHARESHARE
INDIVIDUALS_**

When you grant or revoke a class permission with the generic permissions calls, the service applies the change to the Item Service in the background. The response is 202 with the ID of an async task. The user's Item Service access changes only when the task completes. To check when the change applies, poll the task.

A class must be mapped to a collection before you can grant on it, and its ontology must have a promoted version. A grant on all classes, aosvc:ontologyclass:*, needs at least one of your own classes mapped in the namespace. The built-in state machine classes don't count.

When you promote a new version over a live one, the service applies the class permissions to the new version's collections in the background.

Note: To poll the task, refer to the Get an async task Rest API section.

Permission calls​

You can manage permissions in two ways:

  • The generic permissions calls, /permissions, work with both ontology and class IRNs, including * for every ontology or class in the namespace. A create is idempotent: it updates a matching permission. To grant, you need the share action on the resource and every action you grant. For example, with INDIVIDUALS_SHARE and INDIVIDUALS_READ but not INDIVIDUALS_EDIT, you can grant INDIVIDUALS_READ only. Class grants and revokes return an async task.
  • The ontology and class permission calls, /ontologies/{ontologyId}/permissions and /classes/{classId}/permissions, work on one ontology or class. They need SHARE on the ontology and every action you grant. For a class, you can hold the action on the class or an ancestor. The list calls return every principal's grants on the ontology or class. A class grant applies to the item collections at once and returns no task. If you map another subclass later, send the grant again to cover it. A class revoke removes only the grant on the class, not its item collection grants.

Use the generic calls for class grants. They accept only INDIVIDUALS_* actions on a class. When you revoke a grant that you made with the generic calls, the service also removes its item collection grants.

For a walkthrough, see Granting permissions.

Note: For the permission calls, refer to the Get permissions, Delete a permission, Get ontology permissions, and Grant class permissions Rest API sections.

Required permissions​

OperationPermission
Create an ontologyCREATE on aosvc:ontology:*
Read an ontology, its schema, versions, or impact reportsREAD on the ontology
Change the schema, create or publish a draft, or request or confirm a promotionEDIT on the ontology
Delete an ontologyDELETE on the ontology
Grant or revoke permissions with the ontology and class permission calls, or break another user's edit lockSHARE on the ontology. A grant also needs every action you grant.
Read individuals, their relationships, or telemetry readingsINDIVIDUALS_READ on the class or an ancestor
Create individuals or add telemetry readingsINDIVIDUALS_CREATE on the class or an ancestor
Update an individualINDIVIDUALS_EDIT and INDIVIDUALS_READ
Delete an individualINDIVIDUALS_DELETE and INDIVIDUALS_READ
Add or replace relationshipsINDIVIDUALS_EDIT and INDIVIDUALS_READ on the source's class
Remove a relationshipINDIVIDUALS_EDIT and INDIVIDUALS_READ on the source's class, and INDIVIDUALS_DELETE, which the Item Service checks when it removes the relationship record
Import individualsINDIVIDUALS_CREATE on every class, and INDIVIDUALS_EDIT on every class whose elements carry relationships
Fire a state machine eventCREATE on the event, and INDIVIDUALS_EDIT on every class bound to the machine
Use the AI assistance callsREAD on the ontology. Declaring a class MCP configuration needs EDIT.
Run the reasoner or an OWL previewNo ontology permission

TODO: Describe how to grant CREATE on a state machine event to another user. The service grants it to the user who creates the machine, but the permission calls accept only ontology and class IRNs.