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_EDITandINDIVIDUALS_READ. - To remove a relationship, the Item Service also checks that you have
DELETEpermission 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 action | Item Service action |
|---|---|
INDIVIDUALS_READ | READ |
INDIVIDUALS_CREATE | CREATE |
INDIVIDUALS_EDIT | EDIT |
INDIVIDUALS_DELETE | DELETE |
INDIVIDUALS_SHARE | SHARE |
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, withINDIVIDUALS_SHAREandINDIVIDUALS_READbut notINDIVIDUALS_EDIT, you can grantINDIVIDUALS_READonly. Class grants and revokes return an async task. - The ontology and class permission calls,
/ontologies/{ontologyId}/permissionsand/classes/{classId}/permissions, work on one ontology or class. They needSHAREon 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
| Operation | Permission |
|---|---|
| Create an ontology | CREATE on aosvc:ontology:* |
| Read an ontology, its schema, versions, or impact reports | READ on the ontology |
| Change the schema, create or publish a draft, or request or confirm a promotion | EDIT on the ontology |
| Delete an ontology | DELETE on the ontology |
| Grant or revoke permissions with the ontology and class permission calls, or break another user's edit lock | SHARE on the ontology. A grant also needs every action you grant. |
| Read individuals, their relationships, or telemetry readings | INDIVIDUALS_READ on the class or an ancestor |
| Create individuals or add telemetry readings | INDIVIDUALS_CREATE on the class or an ancestor |
| Update an individual | INDIVIDUALS_EDIT and INDIVIDUALS_READ |
| Delete an individual | INDIVIDUALS_DELETE and INDIVIDUALS_READ |
| Add or replace relationships | INDIVIDUALS_EDIT and INDIVIDUALS_READ on the source's class |
| Remove a relationship | INDIVIDUALS_EDIT and INDIVIDUALS_READ on the source's class, and INDIVIDUALS_DELETE, which the Item Service checks when it removes the relationship record |
| Import individuals | INDIVIDUALS_CREATE on every class, and INDIVIDUALS_EDIT on every class whose elements carry relationships |
| Fire a state machine event | CREATE on the event, and INDIVIDUALS_EDIT on every class bound to the machine |
| Use the AI assistance calls | READ on the ontology. Declaring a class MCP configuration needs EDIT. |
| Run the reasoner or an OWL preview | No 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.