Roles resource (Data API 19.5)

Summary

Http Method Resource Description
GET /roles Action to get all the access roles with no filtering.
GET /roles/{id} Action to get a single access role.
PUT /roles/{id} Action to create an access role.
DELETE /roles/{id} Action to delete an access role.
GET /roles/{id}/permissions Retrieves a list of permissions assigned to the given role.
PUT /roles/{id}/permissions Assigns permissions to the given role. This will replace the current permission assignments. For the 'Administrator' role only adjustments for custom module permissions will be processed but other given permissions will be ignored.
POST /roles/{id}/user_search Searches for users of the specified access role.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

  • login - String
  • email - String
  • first_name - String
  • last_name - String
  • external_id - String
  • last_login_date - Date
  • is_locked - Boolean
  • is_disabled - Boolean

The output of the query can also be sorted. These are the list of sortable attributes:

  • login - String
  • email - String
  • first_name - String
  • last_name - String
  • external_id - String
  • last_login_date - Date
GET /roles/{id}/users Action to get all the users assigned to the specified access role.
PUT /roles/{id}/users/{login} Action to assign a user to an access role
DELETE /roles/{id}/users/{login} Action to unassign a user to an access role

Get public Access Roles

Action to get all the access roles with no filtering.

Url

GET https://hostname:port/dw/data/v19_5/roles?start={Integer}&count={Integer}&select={String}&expand={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Roles

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
expand String List of expansions.  
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

Sample

REQUEST:
GET /s/-/dw/data/v19_5/roles?select=(**)&expand=users HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.72ed5
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 294836
Content-Type: application/json; charset=UTF-8

{
    "_v": "19.5",
    "_type": "roles",
    "count": 20,
    "data": [
        {
            "_type": "role",
            "_resource_state": "8a70837a2a5c1af95d5fc5e61686e41d89f62ce43257d72e7a8b4d89ade5d983",
            "description": "The administrator has the rights to perform tasks related to the overall administration of the merchant organization and its users and roles. This access role is not site-specific and will grant the user access to the entire organization.",
            "id": "Administrator",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/Administrator",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "LocaleDude",
                    "locked": false,
                    "login": "localeDude",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "18f70e67257ef0dc691ed33dca14d16b5a1932207ef7a6bf683fea7ea9cf2007",
            "description": "Read and Write Site Preferences of multiple Sites ",
            "id": "MultiSite-Full-ReadWriteSitePreferences",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/MultiSite-Full-ReadWriteSitePreferences",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "MultiSite-Full-ReadWriteSitePreferences",
                    "locked": false,
                    "login": "MultiSite-Full-ReadWriteSitePreferences",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "27b6ba2d4e85ff931fe0312007885b1668ee05ab7d2560e42183f61f4055a7c9",
            "description": "Read and Write Site Preferences of multiple Sites ",
            "id": "MultiSite-ReadWriteSitePreferences",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/MultiSite-ReadWriteSitePreferences",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "MultiSite-ReadWriteSitePreferences",
                    "locked": false,
                    "login": "MultiSite-ReadWriteSitePreferences",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "49821f548f36454ca11c0dedc4a69ca1e0863bd37415055e2da40ff7e2423424",
            "description": "Allowed to manage things global",
            "id": "OrgManager",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/OrgManager",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "OrgDude",
                    "locked": false,
                    "login": "orgDude",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "9ebc0644131de366b60e29c9f9dfc2b6a1019d3969bb5ca8f7060f42feca340a",
            "description": "Allowed to manage roles",
            "id": "RoleManager",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/RoleManager",
            "user_count": 2,
            "user_manager": true,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_login_date": "2017-01-11",
                    "last_name": "RoleDude",
                    "locked": false,
                    "login": "roleDude",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                },
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SecondRoleManager",
                    "locked": false,
                    "login": "secondRoleManager",
                    "preferred_data_locale": "en",
                    "preferred_uilocale": "de"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "7d8a9ab3cc4c95ad372d5a070e2ce06240f2e16cdcbcdbae423a6361e7b60b36",
            "description": "Read SiteGenesis Site Preferences ",
            "id": "SiteGenesis-ReadSitePreferences",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesis-ReadSitePreferences",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesis-ReadSitePreferences",
                    "locked": false,
                    "login": "SiteGenesis-ReadSitePreferences",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "534a2e085d7893cf3a4bb69e63d5670eb3eaa34ba94ea5a01caeb9f75902fd81",
            "description": "Allowed to do agent use cases for site SiteGenesis-Customization and to Create_Order_On_Behalf_Of for sites SiteGenesis-MinConfig, SiteGenesis-Settings and SiteGenesis",
            "id": "SiteGenesisAgent",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisAgent",
            "user_count": 2,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]m",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentMultiRole",
                    "locked": false,
                    "login": "SiteGenesisAgentMultiRole",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                },
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgent",
                    "locked": false,
                    "login": "SiteGenesisAgent",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "c963858ecf3eafba17560d5cb157f3ef1f5c749fb627a807ad3fd1d3a5e76ca4",
            "description": "Allowed to Handle_External_Orders for SiteGenesis-Customization",
            "id": "SiteGenesisAgentExternalOrders",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisAgentExternalOrders",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentExternalOrders",
                    "locked": false,
                    "login": "SiteGenesisAgentExternalOrders",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "9cabd0d7e44d75e4130b28c0255bcfa9d5bff8395d040d8d756ccdcf3bb33268",
            "description": "Allowed to Create_Order_On_Behalf_Of and Adjust_Item_Price for SiteGenesis-Customization",
            "id": "SiteGenesisAgentItemAdjustment",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisAgentItemAdjustment",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentItemAdjustment",
                    "locked": false,
                    "login": "SiteGenesisAgentItemAdjustment",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "6461ddc34b9033ed0962c7b152a48c88d3afc49363905c1acb95d1d2d2854e87",
            "description": "Allowed to Create_Order_On_Behalf_Of and Adjust_Order_Price for SiteGenesis-Customization",
            "id": "SiteGenesisAgentOrderAdjustment",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisAgentOrderAdjustment",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentOrderAdjustment",
                    "locked": false,
                    "login": "SiteGenesisAgentOrderAdjustment",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "91152c94d417fea07ba34a511446c8cd645d35184f3366623067f2880a2b0cad",
            "description": "Allowed to Create_Order_On_Behalf_Of for SiteGenesis-Customization",
            "id": "SiteGenesisAgentOrderCreateOnBehalf",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisAgentOrderCreateOnBehalf",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentOrderCreateOnBehalf",
                    "locked": false,
                    "login": "SiteGenesisAgentOrderCreateOnBehalf",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "d7787329ec3247878c8dd19c0e959d06eb5d9804cfa3678de0d4a0a94c4d8bf4",
            "description": "Allowed to Search_Orders for SiteGenesis-Customization",
            "id": "SiteGenesisAgentOrderSearch",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisAgentOrderSearch",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentOrderSearch",
                    "locked": false,
                    "login": "SiteGenesisAgentOrderSearch",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "2fa3578a05ca203ac3384f7ba2a9e6e786ecec4e823e22f6d89bfdc9454ad45d",
            "description": "Allowed to Create_Order_On_Behalf_Of and Adjust_Shipping_Price for SiteGenesis-Customization",
            "id": "SiteGenesisAgentShippingAdjustment",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisAgentShippingAdjustment",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentShippingAdjustment",
                    "locked": false,
                    "login": "SiteGenesisAgentShippingAdjustment",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "6313d29bb37df05e39a3d4ec693d6a0d1c38d494c14376674527079c23b0ae60",
            "description": "Allowed to Adjust_Item_Price, Adjust_Shipping_Price, Adjust_Order_Price and Handle_External_Orders for SiteGenesis-Customization",
            "id": "SiteGenesisBfl",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisBfl",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "testAgentBfl",
                    "locked": false,
                    "login": "testAgentBfl",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "1bce5ab4efa425510f14d6e6f85d04060b6843a71567137fc819573d44538fcc",
            "description": "Allowed to manage only site SiteGenesis-DE",
            "id": "SiteGenesisDEManager",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisDEManager",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisDEDude",
                    "locked": false,
                    "login": "SiteGenesisDEDude",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.7691ea3d598f2159",
            "description": "Allowed to manage only site SiteGenesis",
            "id": "SiteGenesisManager",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisManager",
            "user_count": 4,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentMultiRole",
                    "locked": false,
                    "login": "SiteGenesisAgentMultiRole",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                },
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisOAuth2",
                    "locked": false,
                    "login": "SiteGenesisOAuth2",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                },
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_login_date": "2017-01-11",
                    "last_name": "SiteGenesisDude",
                    "locked": false,
                    "login": "SiteGenesisDude",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                },
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisOAuth",
                    "locked": false,
                    "login": "SiteGenesisOAuth",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "01ec043647372212f349c3abe96fcf402d1ea4b5353103b4187d7ac9851de94b",
            "description": "Allowed to Create_Order_On_Behalf_Of and Search_Orders for SiteGenesis-Customization",
            "id": "SiteGenesisNoPriceAdjustment",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/SiteGenesisNoPriceAdjustment",
            "user_count": 1,
            "user_manager": false,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "SiteGenesisAgentLimited",
                    "locked": false,
                    "login": "SiteGenesisLimited",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "896cbc90eeb44a199f85b3fba984639f73ab4d568c6ab838e6c712a00d7d30b5",
            "description": "Allowed to manage users",
            "id": "UserManager",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/UserManager",
            "user_count": 1,
            "user_manager": true,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_login_date": "2017-01-11",
                    "last_name": "UserDude",
                    "locked": false,
                    "login": "userDude",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        },
        {
            "_type": "role",
            "_resource_state": "025c8cff1b2a5b5ffac36e66e6644d368ceea61f6bcd6e807e37f4c16c8e07ad",
            "description": "Allowed to manage users and roles",
            "id": "UserRoleManager",
            "link": "https://example.com/s/-/dw/data/v19_5/roles/UserRoleManager",
            "user_count": 1,
            "user_manager": true,
            "users": [
                {
                    "_type": "user",
                    "disabled": false,
                    "email": "[email protected]",
                    "first_name": "Ocapi",
                    "last_name": "UserRoleDude",
                    "locked": false,
                    "login": "userRoleDude",
                    "preferred_data_locale": "default",
                    "preferred_uilocale": "default"
                }
            ]
        }
    ],
    "expand": [
        "users",
        "permissions"
    ],
    "select": "(**)",
    "start": 0,
    "total": 20
}

Get Access Role

Action to get a single access role.

Url

GET https://hostname:port/dw/data/v19_5/roles/{id}?expand={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Role

Path Parameters

Parameter Type Description Constraints
id String The id of the requested access role. minLength=1

Query Parameters

Parameter Type Description Constraints
expand String The list of expansions.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 RoleNotFoundException

id (String)

Thrown if the access role with the given id does not exist.

Sample

REQUEST:
GET /s/-/dw/data/v19_5/roles/my-role?select=(**)&expand=users,permissions HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.72ed5
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 4128
Content-Type: application/json; charset=UTF-8

{
    "_v": "19.5",
    "_type": "role",
    "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.7691ea3d598f2159",
    "description": "Description of your role",
    "id": "my-role",
    "link": "https://example.com/s/-/dw/data/v19_5/roles/my-role",
    "user_count": 4,
    "user_manager": false,
    "users": [
        {
            "_type": "user",
            "disabled": false,
            "email": "[email protected]",
            "first_name": "Ocapi",
            "last_name": "SiteGenesisAgentMultiRole",
            "locked": false,
            "login": "SiteGenesisAgentMultiRole",
            "preferred_data_locale": "default",
            "preferred_uilocale": "default"
        },
        {
            "_type": "user",
            "disabled": false,
            "email": "[email protected]",
            "first_name": "Ocapi",
            "last_name": "SiteGenesisOAuth2",
            "locked": false,
            "login": "SiteGenesisOAuth2",
            "preferred_data_locale": "default",
            "preferred_uilocale": "default"
        },
        {
            "_type": "user",
            "disabled": false,
            "email": "[email protected]",
            "first_name": "Ocapi",
            "last_login_date": "2017-01-11",
            "last_name": "SiteGenesisDude",
            "locked": false,
            "login": "SiteGenesisDude",
            "preferred_data_locale": "default",
            "preferred_uilocale": "default"
        },
        {
            "_type": "user",
            "disabled": false,
            "email": "[email protected]",
            "first_name": "Ocapi",
            "last_name": "SiteGenesisOAuth",
            "locked": false,
            "login": "SiteGenesisOAuth",
            "preferred_data_locale": "default",
            "preferred_uilocale": "default"
        }
    ]
}

Create Access Role

Action to create an access role.

Url

PUT https://hostname:port/dw/data/v19_5/roles/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Role

Response Document

Role

Path Parameters

Parameter Type Description Constraints
id String The id of the access role to create. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 IdConflictException

bodyID (String)

urlID (String)

Thrown when id in query parameter is different from the id in the body.
403 RoleOperationNotAllowedException

roleId (String)

Thrown when an access role with the id "Support" or "Business Support" should be created.
409 RoleAlreadyExistsException

roleId (String)

Thrown when an access role with the given id already exists.

Sample

REQUEST:
PUT /s/-/dw/data/v19_5/roles/my-role HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.72ed5
Accept: application/json

# in case of success:

RESPONSE:
HTTP/1.1 201 Created
Content-Length: 4128
Content-Type: application/json; charset=UTF-8

{
    "_v": "19.5",
    "_type": "role",
    "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.7691ea3d598f2159",
    "description": "Description of your role",
    "id": "my-role",
    "link": "https://example.com/s/-/dw/data/v19_5/roles/my-role",
    "user_count": 0,
    "user_manager": false
}

# in case of failure:

RESPONSE:
HTTP/1.1 409 Conflict
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"RoleAlreadyExistsException",
    "message":"An access role with id 'my-role' already exists. Delete the existing role before creating a role with the same id."
  }
}

RESPONSE:
HTTP/1.1 403 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"RoleOperationNotAllowedException",
    "message":"Operation is not allowed for role with id 'my-role'."
  }
}

Delete Access Role

Action to delete an access role.

Url

DELETE https://hostname:port/dw/data/v19_5/roles/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
id String The id of the access role to delete. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
403 RoleOperationNotAllowedException

roleId (String)

Thrown if deletion of the given role is not allowed
404 RoleNotFoundException

id (String)

Thrown if the given role does not exist

Sample

REQUEST:
DELETE /s/-/dw/data/v19_5/roles/my-role HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118732ed5
Accept: application/json
x-dw-resource-state: 4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a41823691ea3d598f2159

# in case of success:

RESPONSE:
HTTP/1.1 204 No content

# in case of failure:

RESPONSE:
HTTP/1.1 403 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"RoleOperationNotAllowedException",
    "message":"Operation is not allowed for role with id 'my-role'."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"RoleNotFoundException",
    "message":"No access role with ID 'my-role' was found."
  }
}

Get role permissions

Retrieves a list of permissions assigned to the given role.

Url

GET https://hostname:port/dw/data/v19_5/roles/{id}/permissions

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

RolePermissions

Path Parameters

Parameter Type Description Constraints
id String The id of the requested access role. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 RoleNotFoundException

id (String)

If the specified access role does not exist.

Sample

REQUEST:
GET /s/-/dw/data/v19_5/roles/my-role/permissions HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118732ed5
Accept: application/json

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 2833
x-dw-resource-state: 673705992074cd44247a9898ce5d0ec8e2c8e7bf21498422e1f75a5ec34fc13b
Content-Type: application/json; charset=UTF-8

{
    "_v": "19.5",
    "_type": "role_permissions",
    "_resource_state": "673705992074cd44247a9898ce5d0ec8e2c8e7bf21498422e1f75a5ec34fc13b",
    "functional": {
        "_type": "role_functional_permissions",
        "organization": [
            {
                "_type": "role_functional_permission",
                "name": "Delete_All_Catalogs",
                "type": "functional",
                "value": "ACCESS"
            },
            {
                "_type": "role_functional_permission",
                "name": "Manage_All_Catalogs",
                "type": "functional",
                "value": "ACCESS"
            },
            {
                "_type": "role_functional_permission",
                "name": "WebDAV_Security_Logs_Access",
                "type": "functional",
                "value": "ACCESS"
            }
        ],
        "site": [
            {
                "_type": "role_functional_permission",
                "name": "Manage_Site_Catalog",
                "type": "functional",
                "values": {
                    "SiteGenesis": "ACCESS",
                    "SiteGenesisGlobal": "ACCESS"
                }
            },
            {
                "_type": "role_functional_permission",
                "name": "Manage_Site_Library",
                "type": "functional",
                "values": {
                    "SiteGenesis": "ACCESS",
                    "SiteGenesisGlobal": "ACCESS"
                }
            },
            {
                "_type": "role_functional_permission",
                "name": "Manage_Site_PriceBooks",
                "type": "functional",
                "values": {
                    "SiteGenesis": "ACCESS"
                }
            },
            {
                "_type": "role_functional_permission",
                "name": "Manage_Site_Inventory",
                "type": "functional",
                "values": {
                    "SiteGenesis": "ACCESS"
                }
            }
        ]
    },
    "locale": {
        "_type": "role_locale_permissions",
        "unscoped": [
            {
                "_type": "role_locale_permission",
                "locale_id": "de",
                "type": "locale",
                "value": "ACCESS"
            },
            {
                "_type": "role_locale_permission",
                "locale_id": "default",
                "type": "locale",
                "value": "READONLY"
            },
            {
                "_type": "role_locale_permission",
                "locale_id": "en",
                "type": "locale",
                "value": "READONLY"
            },
            {
                "_type": "role_locale_permission",
                "locale_id": "en_US",
                "type": "locale",
                "value": "ACCESS"
            },
            {
                "_type": role_"locale_permission",
                "locale_id": "fr_FR",
                "type": "locale",
                "value": "ACCESS"
            }
        ]
    },
    "module": {
        "_type": "role_module_permissions",
        "organization": [
            {
                "_type": "role_module_permission",
                "name": "jobmonitor",
                "type": "module",
                "application": "bm",
                "value": "READONLY"
            },
            {
                "_type": "role_module_permission",
                "name": "jobschedules",
                "type": "module",
                "application": "bm",
                "value": "ACCESS",
                "system": true
            }
        ],
        "site": [
            {
                "_type": "role_module_permission",
                "name": "library_content_libraries",
                "system": true,
                "type": "module",
                "application": "bm",
                "values": {
                    "SiteGenesis": "ACCESS",
                    "SiteGenesisGlobal": "READONLY"
                }
            },
            {
                "_type": "role_module_permission",
                "name": "library_folder",
                "system": true,
                "type": "module",
                "application": "bm",
                "values": {
                    "SiteGenesis": "ACCESS",
                    "SiteGenesisGlobal": "ACCESS"
                }
            },
            {
                "_type": "role_module_permission",
                "name": "library_content",
                "system": true,
                "type": "module",
                "application": "bm",
                "values": {
                    "SiteGenesis": "ACCESS",
                    "SiteGenesisGlobal": "READONLY"
                }
            }
        ]
    },
    "webdav": {
        "_type": "role_webdav_permissions",
        "unscoped": [
            {
                "_type": "role_webdav_permission",
                "folder": "/catalogs/apparel-catalog",
                "type": "webdav",
                "value": "ACCESS"
            },
            {
                "_type": "role_webdav_permission",
                "folder": "/catalogs/electronics-catalog",
                "type": "webdav",
                "value": "READONLY"
            },
            {
                "_type": "role_webdav_permission",
                "folder": "/catalogs/storefront-catalog-en",
                "type": "webdav",
                "value": "READONLY"
            },
            {
                "_type": "role_webdav_permission",
                "folder": "/catalogs/storefront-catalog-non-en",
                "type": "webdav",
                "value": "READONLY"
            },
            {
                "_type": "role_webdav_permission",
                "folder": "/libraries/SiteGenesis",
                "type": "webdav",
                "value": "ACCESS"
            },
            {
                "_type": "role_webdav_permission",
                "folder": "/libraries/SiteGenesisGlobal",
                "type": "webdav",
                "value": "READONLY"
            }
        ]
    }
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
    "_v": "19.5",
    "fault": {
        "arguments": {
            "roleId": "RoleManager"
        },
        "type": "RoleNotFoundException",
        "message": "No access role with id 'my-role' found."
    }
}

Set role permissions

Assigns permissions to the given role. This will replace the current permission assignments. For the 'Administrator' role only adjustments for custom module permissions will be processed but other given permissions will be ignored.

Url

PUT https://hostname:port/dw/data/v19_5/roles/{id}/permissions

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

RolePermissions

Response Document

RolePermissions

Path Parameters

Parameter Type Description Constraints
id String The id of the access role for which the permissions will be set. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidPermissionTypeException

permissionID (String)

path (String)

expected (String)

given (String)

If the type of a given permission does not match the expected type.
400 UnknownPermissionException

permissionID (String)

permissionApp (String)

path (String)

If the id of a given permission could not be resolved to a permission.
400 InvalidPermissionValueException

permissionID (String)

path (String)

givenValue (String)

If a permission value is given that is either unknown or not supported for a certain permission.
400 InvalidPermissionValueScopeException

permissionID (String)

path (String)

givenScope (String)

expectedScope (String)

If values are given permission multi values are used where only single values are support or vice versa (e.g. setting 'values' attribute of ModulePermissionWO in organization scope).
400 DefaultLocalePermissionMissingException   If no permission for the 'default' locale is given (permission for 'default' locale is mandatory).
400 UnknownSiteIdException

siteId (String)

If a site specific permission is given for a site that is not known.
400 DuplicatePermissionException

permissionID (String)

path (String)

If a permission is listed more than once within a scope.
400 SystemFlagMissingException

permissionID (String)

path (String)

If the 'system' flag is not set for a module permission.
404 RoleNotFoundException

id (String)

If the specified access role does not exist.
409 ResourceStateConflictException

client (String)

server (String)

In case of state token conflicts.

Sample

REQUEST:
PUT /s/-/dw/data/v19_5/roles/my-role/permissions HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118732ed5
Accept: application/json
{
  "_v" : "19.5",
  "permissions" : {
    "functional" : {
      "organization" : [ {
        "name" : "Delete_All_Catalogs",
        "type" : "functional",
        "value" : "ACCESS"
      } ],
      "site" : [ {
        "name" : "Manage_Site_Catalog",
        "type" : "functional",
        "values" : {
          "SiteGenesis" : "ACCESS",
          "SiteGenesisGlobal" : "ACCESS"
        }
      } ]
    },
    "locale" : {
      "unscoped" : [ {
        "locale_id" : "default",
        "type" : "locale",
        "value" : "READONLY"
      }, {
        "locale_id" : "en_US",
        "type" : "locale",
        "value" : "ACCESS"
      } ]
    },
    "module" : {
      "organization" : [ {
        "name" : "jobmonitor",
        "system" : true,
        "type" : "module",
        "value" : "READONLY"
      } ],
      "site" : [ {
        "name" : "library_content_libraries",
        "system" : true,
        "type" : "module",
        "values" : {
          "SiteGenesis" : "ACCESS",
          "SiteGenesisGlobal" : "READONLY"
        }
      } ]
    },
    "webdav" : {
      "unscoped" : [ {
        "folder" : "/libraries/SiteGenesis",
        "type" : "webdav",
        "value" : "ACCESS"
      }, {
        "folder" : "/libraries/SiteGenesisGlobal",
        "type" : "webdav",
        "value" : "READONLY"
      } ]
    }
  }
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
{
    "_v": "99.9",
    "_type": "permissions",
    "_resource_state": "ecab41f8d4f068ebc5e3290fb4b4d71098b5776a46de6675999a6cb3d7c2c11d",
    "functional": {
        "_type": "functional_permissions",
        "organization": [
            {
                "_type": "functional_permission",
                "name": "Delete_All_Catalogs",
                "type": "functional",
                "value": "ACCESS"
            }
        ],
        "site": [
            {
                "_type": "functional_permission",
                "name": "Manage_Site_Catalog",
                "type": "functional",
                "values": {
                    "SiteGenesis": "ACCESS",
                    "SiteGenesisGlobal": "ACCESS"
                }
            }
        ]
    },
    "locale": {
        "_type": "locale_permissions",
        "unscoped": [
            {
                "_type": "locale_permission",
                "locale_id": "default",
                "type": "locale",
                "value": "READONLY"
            },
            {
                "_type": "locale_permission",
                "locale_id": "en_US",
                "type": "locale",
                "value": "ACCESS"
            }
        ]
    },
    "module": {
        "_type": "module_permissions",
        "organization": [
            {
                "_type": "module_permission",
                "name": "jobmonitor",
                "system": true,
                "type": "module",
                "value": "READONLY"
            }
        ],
        "site": [
            {
                "_type": "module_permission",
                "name": "library_content_libraries",
                "system": true,
                "type": "module",
                "values": {
                    "SiteGenesis": "ACCESS",
                    "SiteGenesisGlobal": "READONLY"
                }
            }
        ]
    },
    "webdav": {
        "_type": "webdav_permissions",
        "unscoped": [
            {
                "_type": "webdav_permission",
                "folder": "/libraries/SiteGenesis",
                "type": "webdav",
                "value": "ACCESS"
            },
            {
                "_type": "webdav_permission",
                "folder": "/libraries/SiteGenesisGlobal",
                "type": "webdav",
                "value": "READONLY"
            }
        ]
    }
}


# in case of failure (unknown permission):

RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "arguments": {
            "path": "locale.unscoped",
            "permissionID": "foobar"
        },
        "type": "UnknownPermissionException",
        "message": "Permission 'foobar' in path 'locale.unscoped' is unknown."
    }
}


# in case of failure (invalid permission type):

RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "arguments": {
            "expected": "locale",
            "given": "foo",
            "path": "locale.unscoped",
            "permissionID": "en_US"
        },
        "type": "InvalidPermissionTypeException",
        "message": "Expected permission type 'locale' but got 'foo' for permission 'en_US' in path 'locale.unscoped'."
    }
}


# in case of failure (invalid permission value):

RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "arguments": {
            "givenValue": "BAR",
            "path": "module.site",
            "permissionID": "library_content_libraries(system)"
        },
        "type": "InvalidPermissionValueException",
        "message": "Permission 'library_content_libraries(system)' in path 'module.site' does not support a value of 'BAR'."
    }
}


# in case of failure (invalid permission scope):

RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "arguments": {
            "expectedScope": "single",
            "givenScope": "multi",
            "path": "webdav.unscoped",
            "permissionID": "/libraries/SiteGenesis"
        },
        "type": "InvalidPermissionValueScopeException",
        "message": "Permission '/libraries/SiteGenesis' in path 'webdav.unscoped' provided multi value but expected single value."
    }
}


# in case of failure (missing default locale permission):

RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "type": "DefaultLocalePermissionMissingException",
        "message": "Permission for 'default' locale is missing."
    }
}


# in case of failure (unkown site):

RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "arguments": {
            "siteId": "Foobar"
        },
        "type": "UnknownSiteIdException",
        "message": "The site id 'Foobar' is unknown."
    }
}


# in case of failure (duplicate permission):
RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "arguments": {
            "path": "module.site",
            "permissionID": "library_content_libraries(system)"
        },
        "type": "DuplicatePermissionException",
        "message": "Permission 'library_content_libraries(system)' in path 'module.site' is provided multiple times."
    }
}

Search for Users on a public Access Role

Searches for users of the specified access role.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

The output of the query can also be sorted. These are the list of sortable attributes:

Url

POST https://hostname:port/dw/data/v19_5/roles/{id}/user_search

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

SearchRequest

Response Document

UserSearchResult

Path Parameters

Parameter Type Description Constraints
id String   minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedSearchParameterException   Thrown if the query is ill-formed.
404 RoleNotFoundException

id (String)

If the specified access role does not exist.

Sample

REQUEST:
POST /s/-/dw/data/v19_5/roles/my-role/user_search HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.72ed5
Accept: application/json

{
    "query": {
        "text_query": {
            "fields": [
                "login"
            ],
            "search_phrase": "Dude"
        }
    },
    "select": "(**)"
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 432
Content-Type: application/json; charset=UTF-8

{
    "_v": "19.5",
    "_type": "user_search_result",
    "count": 1,
    "hits": [
        {
            "_type": "user",
            "disabled": false,
            "email": "[email protected]",
            "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
            "first_name": "Ocapi",
            "last_login_date": "2017-01-11",
            "last_name": "SiteGenesisDude",
            "locked": false,
            "login": "SiteGenesisDude",
            "preferred_data_locale": "default",
            "preferred_uilocale": "default"
        }
    ],
    "query": {
        "text_query": {
            "_type": "text_query",
            "fields": [
                "login"
            ],
            "search_phrase": "Dude"
        }
    },
    "select": "(**)",
    "start": 0,
    "total": 1
}

# in case of failure:

RESPONSE:
HTTP/1.1 400 Bad Request
{
    "_v": "19.5",
    "fault": {
        "type": "ExternalIdNotAllowedException",
        "message": "Attribute 'external_id' is not allowed with the current server settings."
    }
}

Get Users assigned to an Access Role

Action to get all the users assigned to the specified access role.

Url

GET https://hostname:port/dw/data/v19_5/roles/{id}/users?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Users

Path Parameters

Parameter Type Description Constraints
id String ID of the access role. minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 RoleNotFoundException

id (String)

Thrown if the access role with the given id does not exist.

Sample

REQUEST:
GET /s/-/dw/data/v19_5/roles/my-role/users?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.72ed5
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 539
Content-Type: application/json; charset=UTF-8

{
    "_v": "19.5",
    "_type": "users",
    "count": 2,
    "data": [
        {
            "_type": "user",
            "disabled": false,
            "email": "[email protected]",
            "first_name": "Ocapi",
            "last_login_date": "2017-01-12",
            "last_name": "RoleDude",
            "locked": false,
            "login": "roleDude",
            "preferred_data_locale": "default",
            "preferred_uilocale": "default"
        },
        {
            "_type": "user",
            "disabled": false,
            "email": "[email protected]",
            "first_name": "Ocapi",
            "last_name": "SecondRoleManager",
            "locked": false,
            "login": "secondRoleManager",
            "preferred_data_locale": "en",
            "preferred_uilocale": "de"
        }
    ],
    "select": "(**)",
    "start": 0,
    "total": 2
}

Assign User to Access Role

Action to assign a user to an access role

Url

PUT https://hostname:port/dw/data/v19_5/roles/{id}/users/{login}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

User

Path Parameters

Parameter Type Description Constraints
id String ID of the access role. minLength=1
login String Login of the user. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidRoleException

roleId (String)

Thrown if the access role with the given id does not exist.
400 InvalidUserLoginException

login (String)

Thrown if a user with the given login does not exist.
403 UserOperationNotAllowedException

login (String)

Thrown if the operation is not allowed.

Sample

REQUEST:
PUT /s/-/dw/data/v19_5/roles/my-role/users/my-user HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Accept: application/json

# in case of success:

RESPONSE:
HTTP/1.1 201 Created
Content-Length: 539
Content-Type: application/json; charset=UTF-8
{
  "_type": "user",
  "disabled": false,
  "email": "[email protected]",
  "first_name": "Ocapi",
  "last_login_date": "2017-01-12",
  "last_name": "RoleDude",
  "locked": false,
  "login": "roleDude"
}

# in case of failure:

RESPONSE:
HTTP/1.1 400 Bad Request
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"InvalidUserLoginException",
    "message":"A user with login name 'my-user' does not exist."
  }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"InvalidRoleException",
    "message":"The role 'my-role' does not exist."
  }
}

RESPONSE:
HTTP/1.1 403 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"UserOperationNotAllowedException",
    "message":"The operation is not allowed for the user with login 'my-user'."
  }
}

Unassign User to Access Role

Action to unassign a user to an access role

Url

DELETE https://hostname:port/dw/data/v19_5/roles/{id}/users/{login}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
id String ID of the access role. minLength=1
login String Login of the user. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
403 UserOperationNotAllowedException

login (String)

Thrown if the admin user is unassigned from the Administrator role.
404 RoleNotFoundException

id (String)

Thrown if the access role with the given id does not exist.
404 UserNotFoundException

login (String)

Thrown if a user with the given login does not exist.

Sample

REQUEST:
DELETE /s/-/dw/data/v19_5/roles/my-role/users/my-user HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Accept: application/json

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 403 Forbidden
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"UserOperationNotAllowedException",
    "message":"Operation is not allowed for user with login 'my-user'."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"RoleNotFoundException",
    "message":"No access role with ID 'my-role' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"19.5",
  "fault":{
    "type":"UserNotFoundException",
    "message":"No user with login 'my-user' was found."
  }
}