Skip to main content
REST API reference

Manage role privilege path

PDFs

Overview

A role can comprise of multiple tuples and each tuple consists of a REST API path or command/command directory path and its access level. If the tuple refers to a command/command directory path, it may optionally be associated with a query. These APIs can be used to retrieve or modify the associated access level and optional query. They can also be used to delete one of the constituent REST API paths or command/command directory paths within a role. The REST API path can be a resource-qualified endpoint. Currently, the only supported resource-qualified endpoints are the following:

Snapshots APIs

– /api/storage/volumes/{volume.uuid}/snapshots

File System Analytics APIs

– /api/storage/volumes/{volume.uuid}/files

– /api/storage/volumes/{volume.uuid}/top-metrics/clients

– /api/storage/volumes/{volume.uuid}/top-metrics/directories

– /api/storage/volumes/{volume.uuid}/top-metrics/files

– /api/storage/volumes/{volume.uuid}/top-metrics/users

– /api/svm/svms/{svm.uuid}/top-metrics/clients

– /api/svm/svms/{svm.uuid}/top-metrics/directories

– /api/svm/svms/{svm.uuid}/top-metrics/files

– /api/svm/svms/{svm.uuid}/top-metrics/users

ONTAP S3 APIs

– /api/protocols/s3/services/{svm.uuid}/users

Artificial Intelligence Data Engine (AIDE) APIs

Data Compute Node (DCN) APIs

– /api/dcn/cluster/nodes/{node.uuid}/metrics

– /api/dcn/network/ports/{port.uuid}/metrics

Data-Engine APIs

– /api/data-engine/policies/{policy.uuid}/versions

– /api/data-engine/workspaces/{workspace.uuid}/acls

– /api/data-engine/workspaces/{workspace.uuid}/data-collections

– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/acls

– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{entity.uuid}/entities

– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/search

– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/versions

– /api/data-engine/workspaces/{workspace.uuid}/data-collections/{datacollection.uuid}/versions/{version.uuid}/diffs

– /api/data-engine/workspaces/{workspace.uuid}/data-sources

– /api/data-engine/workspaces/{workspace.uuid}/entities

– /api/data-engine/workspaces/{workspace.uuid}/entities/{entity.uuid}/custom-attributes

– /api/data-engine/workspaces/{workspace.uuid}/queries

– /api/data-engine/workspaces/{workspace.uuid}/queries/{query.uuid}/entities

– /api/data-engine/workspaces/{workspace.uuid}/versions

– /api/data-engine/workspaces/{workspace.uuid}/versions/{version.uuid}/diffs

When used in the context of data collection APIs, {version.uuid} refers to a data collection version. In the context of workspace APIs, it refers to a workspace version.

In the APIs above, and in the context of REST roles, the wildcard character * can be used in place of {volume.uuid} or {svm.uuid} to represent all volumes or all SVMs, depending on whether the REST endpoint references volumes or SVMs. The {volume.uuid} corresponds to the -instance-uuid field in the output of the "volume show" command at the diagnostic privilege level. It can also be retrieved through the REST endpoint /api/storage/volumes.

In the AIDE APIs described above, and in the context of REST roles, the wildcard character * can be used in place of variable components in the Uniform Resource Identifier (URI) path, such as {node.uuid}, {port.uuid}, {policy.uuid}, {workspace.uuid}, {datacollection.uuid}, {entity.uuid}, {version.uuid}, or {query.uuid}. The specific variable to be replaced depends on whether the REST endpoint references nodes, ports, policies, workspaces, data collections, entities, versions, or queries.

However, when using the wildcard character * in place of a variable component in a URI path, it must replace

all variable components in that path. Mixing wildcards and specific values for different variable components within the same URI path is not supported in REST roles. For example, a URI path such as /api/data-engine/workspaces/c6e1b325-4125-11f0-abb5-bc2411f6fd43/data-collections/*/search is not supported.

In summary, only the following two types of resource-qualified endpoints are supported in a REST role:

  • All variable components in the URI path are specific values. Example: /api/data-engine/workspaces/c6e1b325-4125-11f0-abb5-bc2411f6fd43/data-collections/b09b6d25-4126-11f0-abb5-bc2411f6fd43/search

  • All variable components in the URI path are wildcards. Example: /api/data-engine/workspaces//data-collections//search

AIDE APIs are supported only in cluster-scoped REST roles, not in SVM-scoped REST roles.

The role can be SVM-scoped or cluster-scoped.

Specify the owner UUID and the role name in the URI path. The owner UUID corresponds to the UUID of the SVM for which the role has been created and can be obtained from the response body of a GET request performed on one of the following APIs: /api/security/roles for all roles /api/security/roles/?scope=svm for SVM-scoped roles /api/security/roles/?owner.name=</i> for roles in a specific SVM This API response contains the complete URI for each tuple of the role and can be used for GET, PATCH, or DELETE operations.

Note The access level for paths in pre-defined roles cannot be updated.

Examples

Updating the access level for a REST API path in the privilege tuple of an existing role

# The API:
PATCH "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X PATCH "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fprotocols" -d '{"access":"all"}'

Updating the access level for a command/command directory path in the privilege tuple of an existing role

# The API:
PATCH "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X PATCH "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/netp%20port" -d '{"access":"readonly","query":"-type if-group&#124;vlan"}'

Updating the access level for a resource-qualified endpoint in the privilege tuple of an existing role

# The API:
PATCH "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X PATCH "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fstorage%2Fvolumes%2F742ef001-24f0-4d5a-9ec1-2fdaadb282f4%2Ffiles" -d '{"access":"readonly"}'

Updating the access level for an AIDE resource-qualified endpoint in the privilege tuple of an existing role

# The API:
PATCH "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X PATCH "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/cluster_role1/privileges/%2Fapi%2Fdata-engine%2Fpolicies%2F%2A%2Fversions" -d '{"access":"readonly"}'

Retrieving the access level for a REST API path in the privilege tuple of an existing role

# The API:
GET "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X GET "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fprotocols"

# The response:
{
"owner": {
  "uuid": "aaef7c38-4bd3-11e9-b238-0050568e2e25"
},
"name": "svm_role1",
"path": "/api/protocols",
"access": "all",
"_links": {
  "self": {
    "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fprotocols"
  }
}
}

Retrieving the access level for a command/command directory path in the privilege tuple of an existing role

# The API:
GET "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X GET "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/net%20port"

# The response:
{
"owner": {
  "uuid": "aaef7c38-4bd3-11e9-b238-0050568e2e25"
},
"name": "svm_role1",
"path": "net port",
"query":"-type if-group&#124;vlan",
"access": "readonly",
"_links": {
  "self": {
    "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/net%20port"
  }
}
}

Retrieving the access level for a resource-qualified endpoint in the privilege tuple of an existing role

# The API:
GET "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X GET "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fstorage%2Fvolumes%2Fd0f3b91a-4ce7-4de4-afb9-7eda668659dd%2F%2Fsnapshots"

# The response:
{
"owner": {
  "uuid": "aaef7c38-4bd3-11e9-b238-0050568e2e25"
},
"name": "svm_role1",
"path": "/api/storage/volumes/d0f3b91a-4ce7-4de4-afb9-7eda668659dd/snapshots",
"access": "all",
"_links": {
  "self": {
    "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fstorage%2Fvolumes%2Fd0f3b91a-4ce7-4de4-afb9-7eda668659dd%2Fsnapshots"
  }
}
}

Retrieving the access level for an AIDE resource-qualified endpoint in the privilege tuple of an existing role

# The API:
GET "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X GET "https://<mgmt-ip>/api/security/roles/223e4567-e89b-12d3-a456-426614174000/cluster_role1/privileges/%2Fapi%2Fdata-engine%2Fworkspaces%2Fd0f3b91a-4ce7-4de4-afb9-7eda668659dd%2Fentities"

# The response:
{
"owner": {
  "uuid": "223e4567-e89b-12d3-a456-426614174000"
},
"name": "cluster_role1",
"path": "/api/data-engine/workspaces/d0f3b91a-4ce7-4de4-afb9-7eda668659dd/entities",
"access": "readonly",
"_links": {
  "self": {
    "href": "/api/security/roles/223e4567-e89b-12d3-a456-426614174000/cluster_role1/privileges/%2Fapi%2Fdata-engine%2Fworkspaces%2Fd0f3b91a-4ce7-4de4-afb9-7eda668659dd%2Fentities"
  }
}
}

Deleting a privilege tuple, containing a REST API path, from an existing role

# The API:
DELETE "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X DELETE "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fprotocols"

Deleting a privilege tuple, containing a command/command directory path, from an existing role

# The API:
DELETE "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X DELETE "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/net%20port"

Deleting a privilege tuple, containing a resource-qualified endpoint, from an existing role

# The API:
DELETE "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X DELETE "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fstorage%2Fsvm%2F6e000659-9a16-11ec-819e-005056bb1a7c%2Ftop-metrics%2Ffiles"

Deleting a privilege tuple, containing an AIDE resource-qualified endpoint, from an existing role

# The API:
DELETE "/api/security/roles/{owner.uuid}/{name}/privileges/{path}"

# The call:
curl -X DELETE "https://<mgmt-ip>/api/security/roles/a6786ae5-93a0-411c-bcfd-16c53ecff612/cluster_role1/privileges/%2Fapi%2Fdcn%2Fnetwork%2Fports%2F91796b96-5207-4d0b-93fb-7a2062b8358e%2Fmetrics"