Roles endpoint
Roles define the access that an administrator, a specialist, or an end-user has to resources in your organization. In a role-based access control environment, user access provisioning is group through common responsibilities and needs. A role has a given set of permissions and members of your organization can be assigned to one or more roles, depending on the scope of view or write access they need.
The /roles
endpoint in the attribute-based access control API allows you to programmatically manage roles in your organization.
Getting started
The API endpoint used in this guide is part of the attribute-based access control API. Before continuing, please review the getting started guide for links to related documentation, a guide to reading the sample API calls in this document, and important information regarding required headers that are needed to successfully make calls to any Experience Platform API.
Retrieve a list of roles list
You can list all existing roles belonging to your organization by making a GET request to the /roles
endpoint.
API format
GET /roles/
Request
The following request retrieves a list of roles belonging to your organization.
curl -X GET \
https://platform.adobe.io/data/foundation/access-control/administration/roles \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
Response
A successful response returns a list of roles in your organization, including information on their respective role type, permission sets, and subject attributes.
{
"roles": [
{
"id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"name": "Administrator Role",
"description": "Role for administrator type of responsibilities and access",
"roleType": "user-defined",
"permissionSets": [
"manage-datasets",
"manage-schemas"
],
"sandboxes": [
"prod"
],
"subjectAttributes": {
"labels": [
"core/S1"
]
},
"createdBy": "{CREATED_BY}",
"createdAt": 1648153201825,
"modifiedBy": "{MODIFIED_BY}",
"modifiedAt": 1648153201825,
"etag": null
}
],
"_page": {
"limit": 1,
"count": 1
},
"_links": {
"next": {
"href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"templated": true
},
"page": {
"href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"templated": true
},
"subjects": {
"href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"templated": true
}
}
}
id
name
description
roleType
user-defined
and system-defined
.permissionSets
sandboxes
subjectAttributes
subjectAttributes.labels
Look up a role lookup
You can look up an individual role by making a GET request that includes the corresponding roleId
in the request path.
API format
GET /roles/{ROLE_ID}
Request
The following request retrieves information for {ROLE_ID}
.
curl -X GET \
https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
Response
A successful response returns details for the queried role ID, including information on its role type, permission sets, and subject attributes.
{
"id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"name": "Administrator Role",
"description": "Role for administrator type of responsibilities and access",
"roleType": "user-defined",
"permissionSets": [
"manage-datasets",
"manage-schemas"
],
"sandboxes": [
"prod"
],
"subjectAttributes": {
"labels": [
"core/S1"
]
},
"createdBy": "{CREATED_BY}",
"createdAt": 1648153201825,
"modifiedBy": "{MODIFIED_BY}",
"modifiedAt": 1648153201825,
"etag": null
}
id
name
description
roleType
user-defined
and system-defined
.permissionSets
sandboxes
subjectAttributes
subjectAttributes.labels
Look up subjects by role ID
You can also retrieve subjects by making a GET request to the /roles
endpoint while providing a {ROLE_ID}.
API format
GET /roles/{ROLE_ID}/subjects
Request
The following request retrieves subjects associated with 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
.
curl -X GET \
https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809/subjects \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
Response
A successful response returns the subjects associated with the queried role ID, including the corresponding subject ID and subject type.
{
"items": [
{
"roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"subjectType": "user",
"subjectId": "03Z07HFQCCUF3TUHAX274206@AdobeID"
},
{
"roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"subjectType": "user",
"subjectId": "PIRJ7WE5T3QT9Z4TCLVH86DE@AdobeID"
},
{
"roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"subjectType": "user",
"subjectId": "WHPWE00MC26SHZ7AKBFG403D@AdobeID"
},
]
"_page": {
"limit": 0,
"count": 0
},
"_links": {
"self": {
"href": "/roles/{ROLE_ID}/subjects",
"templated": false,
"type": null,
"method": null
},
"page": {
"href": "/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}",
"templated": true,
"type": null,
"method": null
}
}
}
roleId
subjectType
subjectId
Create a role create
To create a new role, make a POST request to the /roles
endpoint while providing values for your role’s name, description, and role type.
API format
POST /roles/
Request
curl -X POST \
https://platform.adobe.io/data/foundation/access-control/administration/roles \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}'
-d'{
"name": "Administrator Role",
"description": "Role for administrator type of responsibilities and access",
"roleType": "user-defined"
}'
name
description
roleType
user-defined
and system-defined
.Response
A successful response returns your newly created role, with its corresponding role ID, as well as information on its role type, permission sets, and subject attributes.
{
"id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"name": "Administrator Role",
"description": "Role for administrator type of responsibilities and access",
"roleType": "user-defined",
"permissionSets": [
"manage-datasets",
"manage-schemas"
],
"sandboxes": [
"prod"
],
"subjectAttributes": {
"labels": [
"core/S1"
]
},
"createdBy": "{CREATED_BY}",
"createdAt": 1648153201825,
"modifiedBy": "{MODIFIED_BY}",
"modifiedAt": 1648153201825,
"etag": null
}
id
name
description
roleType
user-defined
and system-defined
.permissionSets
sandboxes
subjectAttributes
subjectAttributes.labels
Update a role patch
You can update a role’s properties by making a PATCH request to the /roles
endpoint while providing the corresponding role ID and values for the operations you want to apply.
API format
PATCH /roles/{ROLE_ID}
Request
curl -X PATCH \
https://platform.adobe.io/data/foundation/access-control/administration/roles/{ROLE_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}'
-d'{
"operations": [
{
"op": "add",
"path": "/description",
"value": "Role with permission sets for admin type of access"
}
]
}'
op
add
, replace
, and remove
.path
value
Response
A successful response returns the updated role, including new values for the properties you chose to update.
{
"id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"name": "Administrator Role",
"description": "Role with permission sets for admin type of access",
"roleType": "user-defined",
"permissionSets": [
"manage-datasets",
"manage-schemas"
],
"sandboxes": [
"prod"
],
"subjectAttributes": {
"labels": [
"core/S1"
]
},
"createdBy": "{CREATED_BY}",
"createdAt": 1648153201825,
"modifiedBy": "{MODIFIED_BY}",
"modifiedAt": 1648153201825,
"etag": null
}
id
name
description
roleType
user-defined
and system-defined
.permissionSets
sandboxes
subjectAttributes
subjectAttributes.labels
Update a role by role ID put
You can update a role by making a PUT request to the /roles
endpoint and specifying the role ID that corresponds to the role you want to update.
API format
PUT /roles/{ROLE_ID}
Request
The following request updates the name, description, and role type for role ID: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809
.
curl -X PUT \
https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}'
-d'{
"name": "Administrator role for ACME",
"description": "New administrator role for ACME",
"roleType": "user-defined"
}'
name
description
roleType
user-defined
and system-defined
.Response
A successful response returns your updated role, including new values for its name, description, and role type.
{
"id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
"name": "Administrator role for ACME",
"description": "New administrator role for ACME",
"roleType": "user-defined",
"permissionSets": [
"manage-datasets",
"manage-schemas"
],
"sandboxes": [
"prod"
],
"subjectAttributes": {
"labels": [
"core/S1"
]
},
"createdBy": "{CREATED_BY}",
"createdAt": 1648153201825,
"modifiedBy": "{MODIFIED_BY}",
"modifiedAt": 1648153201825,
"etag": null
}
id
name
description
roleType
user-defined
and system-defined
.permissionSets
sandboxes
subjectAttributes
subjectAttributes.labels
Update subject by role ID
To update the subjects associated with a role, make a PATCH request to the /roles
endpoint while providing the role ID of the subjects you want to update.
API format
PATCH /roles/{ROLE_ID}/subjects
Request
The following request updates the subjects associated with {ROLE_ID}
.
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/access-control/administration/roles/<ROLE_ID>/subjects' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '[
{
"op": "add",
"path": "/user",
"value": "{USER ID}"
}
]'
op
add
, replace
, and remove
.path
value
Response
A successful response returns your updated role, including new values for the subjects.
{
"subjects": [
[
{
"subjectId": "03Z07HFQCCUF3TUHAX274206@AdobeID",
"subjectType": "user"
}
]
],
"_page": {
"limit": 1,
"count": 1
},
"_links": {
"self": {
"href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects",
"templated": true
},
"page": {
"href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}",
"templated": true
}
}
}
Delete a role delete
To delete a role, make a DELETE request to the /roles
endpoint while specifying the ID of the role you want to delete.
API format
DELETE /roles/{ROLE_ID}
Request
The following request deletes the role with the ID of {ROLE_ID}
.
curl -X DELETE \
https://platform.adobe.io/data/foundation/access-control/administration/roles/{ROLE_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
Response
A successful response returns HTTP status 204 (No Content) and a blank body.
You can confirm the deletion by attempting a lookup (GET) request to the role. You will receive an HTTP status 404 (Not Found) because the role has been removed from the administration.
Add an API credential apicredential
To add an API credential, make a PATCH request to /roles
endpoint while providing the role ID of the subjects.
API format
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/access-control/administration/roles/<ROLE_ID>/subjects' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '[
{
"op": "add",
"path": "/api-integration",
"value": "{TECHNICAL ACCOUNT ID}"
}
]'
op
add
, replace
, and remove
.path
value
Response
A successful response returns HTTP status 204 (No Content) and a blank body.