Permissions
The Application Ontology Service permissions API lets you read, grant, and revoke access to application ontologies and to the individuals of ontology classes. The platform stores every grant as a Passport permission on one of two IRNs:
| IRN | Protects | Actions you can grant | Action needed to share |
|---|---|---|---|
aosvc:ontology:{ontologyId} | The ontology and its whole definition, such as classes, relationships, rules, constraints, actions, state machines, and MCP configuration | READ, CREATE, EDIT, DELETE, SHARE, * | SHARE |
aosvc:ontologyclass:{classId} | The individuals of a class and their relationships | INDIVIDUALS_READ, INDIVIDUALS_CREATE, INDIVIDUALS_EDIT, INDIVIDUALS_DELETE, INDIVIDUALS_SHARE, INDIVIDUALS_* | INDIVIDUALS_SHARE |
Actions match exactly. For example, EDIT doesn't include READ, so grant both if the user needs both. An ontology grant doesn't give access to individuals, and a class grant doesn't give access to the class definition.
Class grants are hierarchy-aware: a grant on a class also reaches the individuals of its subclasses. The platform applies a class grant to the item collections that store the individuals asynchronously. When a call queues this work, the response carries these headers:
| Header | Value |
|---|---|
Location | The URL to poll for the task, /aosvc/api/v1/async-tasks/{taskId}, when the call queues one task |
Link | One <url>; rel="monitor" entry per task, instead of Location, when the call queues several tasks |
X-AOSVC-Reconciliation-Task-Id | The task ID or IDs |
To check when the new access applies, poll the task with Get an async task.
Every call needs an Authorization: Bearer <token> header. For more information on the permission model, see Permissions.
This section contains the following API calls:
- Get permissions
- Create or update permissions
- Delete a permission
- Get ontology permissions
- Grant ontology permissions
- Revoke an ontology permission
- Get class permissions
- Grant class permissions
- Revoke a class permission
Get permissions
Gets the permissions on one ontology or class IRN. You can read your own permissions without any share action. To read another principal's permissions, you need the share action on the resource.
Endpoints
GET /aosvc/api/v1/permissions
Parameters
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply | Required |
_namespace | String | The namespace of the permission. You can repeat this parameter. Each namespace must be in nsfilter. | Required |
_resourceDesc._irn | String | The ontology or class IRN, such as aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa. A resource ID of * matches every ontology or every class in the namespace. | Required |
_user._id | String | The principal ID, a UUID. Send it together with _user._type. If you omit both, the call returns your own permissions. | Optional |
_user._type | String | The principal type: user, usergroup, or permprofile. Send it together with _user._id. | Optional |
patternmatch | Boolean | Whether to treat the IRN as a pattern. Default is false. | Optional |
Request example
GET /aosvc/api/v1/permissions?nsfilter=myapp&_namespace=myapp&_resourceDesc._irn=aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa&_user._id=6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b&_user._type=usergroup
Response
{
"_pageSize": 1,
"_total": 1,
"_offset": 0,
"_includeTotal": true,
"_list": [
{
"_id": "0b9e8f7a-6c5d-4e3f-9a2b-1c0d9e8f7a6b",
"_namespace": "myapp",
"_resourceDesc": {
"_irn": "aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa"
},
"_user": {
"_id": "6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b",
"_type": "usergroup"
},
"_actions": [
"INDIVIDUALS_READ",
"INDIVIDUALS_EDIT"
]
}
]
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter or _namespace is missing, a namespace isn't in nsfilter, the IRN is malformed or isn't an ontology or class IRN, _user._id isn't a UUID, _user._type is invalid, or _user._id and _user._type aren't sent together. |
401 | Unauthorized |
403 | Forbidden. You asked about another principal without the share action on the resource. |
404 | Not Found. The ontology or class doesn't exist in the namespace, or the class exists only in a draft. |
409 | Conflict. The IRN names a class of an ontology that has no promoted version yet. |
Create or update permissions
Creates or updates one or more permissions. The call is idempotent: if a matching permission exists, the platform updates it.
To grant a permission, you need the share action on the resource and every action you grant. For example, if you hold INDIVIDUALS_SHARE and INDIVIDUALS_READ but not INDIVIDUALS_EDIT, you can grant INDIVIDUALS_READ but not INDIVIDUALS_EDIT.
If at least one class permission succeeds, the call queues a task and returns 202 with the task headers.
Endpoints
PUT /aosvc/api/v1/permissions
Parameters
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply | Required |
Body
The body is a JSON array of permissions, even for one permission.
| Parameter | Type | Description | Required |
|---|---|---|---|
_namespace | String | The namespace of the permission. It must be in nsfilter, and the ontology or class must exist in it. | Required |
_resourceDesc._irn | String | The ontology or class IRN, such as aosvc:ontology:{ontologyId} or aosvc:ontologyclass:{classId}. Use * as the resource ID to cover every ontology or every class in the namespace. A class must be mapped to an item collection, and its ontology must have a promoted version. A class wildcard needs at least one of your own classes mapped in the namespace. The built-in state machine classes don't count. | Required |
_user._id | String | The principal ID, a UUID | Required |
_user._type | String | The principal type: user, usergroup, or permprofile. The type isn't case-sensitive. | Required |
_actions | Array of String | The actions to grant. They must be valid for the IRN type. | Required |
Don't send _criteria or _subresourceDesc. The call rejects them.
The call checks each entry before it writes anything. If an entry is missing a field, the 400 message names the entry and the field, for example permission[0]._resourceDesc is required.
The IRN must be an ontology or class IRN. The call rejects any other IRN, and the message lists the two supported forms.
Example:
[
{
"_namespace": "myapp",
"_resourceDesc": {
"_irn": "aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa"
},
"_user": {
"_id": "6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b",
"_type": "usergroup"
},
"_actions": ["INDIVIDUALS_READ", "INDIVIDUALS_EDIT"]
}
]
Response
Both 200 and 202 can include failures for individual entries, so check _failures. Each _success entry carries the permission _id.
{
"_success": [
{
"_id": "0b9e8f7a-6c5d-4e3f-9a2b-1c0d9e8f7a6b",
"_namespace": "myapp",
"_resourceDesc": {
"_irn": "aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa"
},
"_user": {
"_id": "6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b",
"_type": "usergroup"
},
"_actions": ["INDIVIDUALS_READ", "INDIVIDUALS_EDIT"]
}
],
"_failures": []
}
Codes
| Code | Description |
|---|---|
200 | Success. No class permission succeeded, so no task was queued. |
202 | Accepted. A task was queued for the class permissions that succeeded. The response has the task headers. |
400 | Bad Request. The body is blank, isn't an array, or is empty; an entry isn't an object or is missing a required field; an action is unknown or isn't valid for the IRN; _actions is empty; _criteria or _subresourceDesc is present; or a namespace, IRN, or principal is invalid. |
401 | Unauthorized |
403 | Forbidden. You don't have the share action, or you grant an action you don't hold. |
404 | Not Found. The ontology or class doesn't exist in the namespace, or the class exists only in a draft. |
409 | Conflict. The class's ontology has no promoted version yet, the class isn't mapped to an item collection, or a class wildcard matches none of your own mapped classes in the namespace. |
Delete a permission
Deletes one permission by its ID. You need the share action on the resource and every action the permission holds.
Send the permission ID in the path. DELETE /aosvc/api/v1/permissions?_id={permissionId} has no route and returns 405.
For a class permission, the call also queues a task that removes the grant from the item collections. The user keeps access to the individuals until the task completes. To check when the access ends, poll the task until its _status is COMPLETED. Don't rely on a fixed wait.
Endpoints
DELETE /aosvc/api/v1/permissions/{permissionId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
permissionId | String | The permission ID, a UUID. Get it from the _id of a Get permissions or Create or update permissions response. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must include the permission's namespace. | Required |
Request example
DELETE /aosvc/api/v1/permissions/0b9e8f7a-6c5d-4e3f-9a2b-1c0d9e8f7a6b?nsfilter=myapp
Response
The response has no body. For a class permission, the response has the task headers.
{}
Codes
| Code | Description |
|---|---|
202 | Accepted. The class permission was deleted, and a task was queued to remove its access to the item collections. |
204 | No Content. The ontology permission was deleted. |
400 | Bad Request. The permission ID isn't a UUID. |
401 | Unauthorized |
403 | Forbidden. You don't have the share action, or you don't hold every action in the permission. |
404 | Not Found. No permission has this ID. |
405 | Method Not Allowed. You sent the ID as a query parameter instead of in the path. |
Get ontology permissions
Lists the permissions granted directly on one ontology, for every user, user group, and permission profile. Wildcard grants, such as a grant on aosvc:ontology:*, aren't listed. You need SHARE on the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/permissions
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ontology ID | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the ontology belongs to. | Required |
Request example
GET /aosvc/api/v1/ontologies/a1b2c3d4-e5f6-7890-abcd-ef1234567890/permissions?nsfilter=myapp
Response
[
{
"_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"_namespace": "myapp",
"_resourceDesc": {
"_irn": "aosvc:ontology:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"_user": {
"_id": "9c2b1a0f-8e7d-4c6b-a5f4-3e2d1c0b9a8f",
"_type": "user"
},
"_actions": ["READ", "EDIT"]
}
]
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing or names no namespace. |
401 | Unauthorized |
403 | Forbidden. You don't have SHARE on the ontology. |
404 | Not Found. The ontology doesn't exist, or nsfilter names a namespace that the ontology doesn't belong to. |
Grant ontology permissions
Grants a principal actions on one ontology. You need SHARE on the ontology and every action you grant. For example, to grant *, you need *. If you don't hold one of the actions, the call grants nothing. The response has no body. To get the new permission ID, call Get ontology permissions.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/permissions
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ontology ID | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
_user._id | String | The principal ID, a Passport GUID | Required |
_user._type | String | The principal type: user, usergroup, or permprofile. Default is usergroup. | Optional |
_actions | Array of String | The actions to grant, such as READ, CREATE, EDIT, DELETE, or SHARE. Action names aren't case-sensitive. Use * or ALL for all actions. | Required |
Example:
{
"_user": {
"_id": "9c2b1a0f-8e7d-4c6b-a5f4-3e2d1c0b9a8f",
"_type": "user"
},
"_actions": ["READ", "EDIT"]
}
Response
The response has no body.
{}
Codes
| Code | Description |
|---|---|
204 | No Content. The permission was granted. |
400 | Bad Request. _user or _user._id is missing, _actions is empty, _user._type is invalid, or an action is invalid. |
401 | Unauthorized |
403 | Forbidden. You don't have SHARE on the ontology, or you grant an action you don't hold. |
404 | Not Found. The ontology doesn't exist, or nsfilter names a namespace that the ontology doesn't belong to. |
Revoke an ontology permission
Deletes one permission on an ontology. You need SHARE on the ontology.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/permissions/{permissionId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ontology ID | Required |
permissionId | String | The permission ID. Get it from Get ontology permissions. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the ontology belongs to. | Required |
Request example
DELETE /aosvc/api/v1/ontologies/a1b2c3d4-e5f6-7890-abcd-ef1234567890/permissions/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f?nsfilter=myapp
Response
The response has no body.
{}
Codes
| Code | Description |
|---|---|
204 | No Content. The permission was deleted. |
400 | Bad Request. nsfilter is missing or names no namespace. |
401 | Unauthorized |
403 | Forbidden. You don't have SHARE on the ontology. |
404 | Not Found. The ontology doesn't exist, nsfilter names a namespace that the ontology doesn't belong to, or no permission with this ID is on this ontology. |
Get class permissions
Lists the permissions granted directly on one class, for every user, user group, and permission profile. The list doesn't include grants on ancestor classes or wildcard grants, such as a grant on aosvc:ontologyclass:*. You need SHARE on the ontology that owns the class.
Endpoints
GET /aosvc/api/v1/classes/{classId}/permissions
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The class ID | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the owning ontology belongs to. | Required |
Request example
GET /aosvc/api/v1/classes/c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa/permissions?nsfilter=myapp
Response
[
{
"_id": "0b9e8f7a-6c5d-4e3f-9a2b-1c0d9e8f7a6b",
"_namespace": "myapp",
"_resourceDesc": {
"_irn": "aosvc:ontologyclass:c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa"
},
"_user": {
"_id": "6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b",
"_type": "usergroup"
},
"_actions": ["INDIVIDUALS_READ"]
}
]
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing or names no namespace. |
401 | Unauthorized |
403 | Forbidden. You don't have SHARE on the owning ontology. |
404 | Not Found. The class doesn't exist or exists only in a draft, or nsfilter names a namespace that the owning ontology doesn't belong to. |
Grant class permissions
Grants a principal actions on one class. You need SHARE on the ontology that owns the class. You also need every action you grant, on the class or one of its ancestors. If you don't hold one of the actions, the call grants nothing. The ontology must have a promoted version.
The call writes the grant on the class and applies it right away to the item collections of the class and its mapped subclasses. It doesn't queue a task. If you map another subclass to a collection later, send the grant again to cover it.
Note: This call doesn't check that the actions are valid for a class. To have them checked, use Create or update permissions with a class IRN. That call accepts only
INDIVIDUALS_*actions on a class.
Endpoints
POST /aosvc/api/v1/classes/{classId}/permissions
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The class ID | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the owning ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
_user._id | String | The principal ID, a Passport GUID | Required |
_user._type | String | The principal type: user, usergroup, or permprofile. Default is usergroup. | Optional |
_actions | Array of String | The actions to grant. Action names aren't case-sensitive. Use * or ALL for all actions. | Required |
Example:
{
"_user": {
"_id": "6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b",
"_type": "usergroup"
},
"_actions": ["INDIVIDUALS_READ"]
}
Response
The response has no body.
{}
Codes
| Code | Description |
|---|---|
204 | No Content. The permission was granted. |
400 | Bad Request. _user or _user._id is missing, _actions is empty, _user._type is invalid, or an action is invalid. |
401 | Unauthorized |
403 | Forbidden. You don't have SHARE on the owning ontology, or you grant an action you don't hold. |
404 | Not Found. The class doesn't exist or exists only in a draft, or nsfilter names a namespace that the owning ontology doesn't belong to. |
409 | Conflict. The ontology has no promoted version yet. |
Revoke a class permission
Deletes one permission on a class. You need SHARE on the ontology that owns the class.
The call deletes only the grant on the class. It doesn't remove the grants that Grant class permissions added to the item collections.
Endpoints
DELETE /aosvc/api/v1/classes/{classId}/permissions/{permissionId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The class ID | Required |
permissionId | String | The permission ID. Get it from Get class permissions. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the owning ontology belongs to. | Required |
Request example
DELETE /aosvc/api/v1/classes/c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa/permissions/0b9e8f7a-6c5d-4e3f-9a2b-1c0d9e8f7a6b?nsfilter=myapp
Response
The response has no body.
{}
Codes
| Code | Description |
|---|---|
204 | No Content. The permission was deleted. |
400 | Bad Request. nsfilter is missing or names no namespace. |
401 | Unauthorized |
403 | Forbidden. You don't have SHARE on the owning ontology. |
404 | Not Found. The class doesn't exist or exists only in a draft, nsfilter names a namespace that the owning ontology doesn't belong to, or no permission with this ID is on this class. |