Roles resource (Data API 18.6)

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.
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 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 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/v18_6/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
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/v18_6/roles?select=(**)&expand=users HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.62ed5
Accept: application/json

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

{
    "_v": "18.6",
    "_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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/roles/SiteGenesisAgent",
            "user_count": 2,
            "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": "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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/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.6691ea3d598f2159",
            "description": "Allowed to manage only site SiteGenesis",
            "id": "SiteGenesisManager",
            "link": "https://example.com/s/-/dw/data/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/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/v18_6/roles/my-role?select=(**)&expand=users,permissions HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.62ed5
Accept: application/json

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

{
    "_v": "18.6",
    "_type": "role",
    "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.6691ea3d598f2159",
    "description": "Description of your role",
    "id": "my-role",
    "link": "https://example.com/s/-/dw/data/v18_6/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]ple.com",
            "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/v18_6/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

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.

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/v18_6/roles/my-role HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.62ed5
Accept: application/json

# in case of success:

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

{
    "_v": "18.6",
    "_type": "role",
    "_resource_state": "4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.6691ea3d598f2159",
    "description": "Description of your role",
    "id": "my-role",
    "link": "https://example.com/s/-/dw/data/v18_6/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":"18.6",
  "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":"18.6",
  "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/v18_6/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 create.	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

Sample

REQUEST:
DELETE /s/-/dw/data/v18_6/roles/my-role HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.62ed5
Accept: application/json
x-dw-resource-state: 4553edb0fa1ea413fa9646bb376182c8eeb721f47e7a418.6691ea3d598f2159

# 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":"18.6",
  "fault":{
    "type":"RoleOperationNotAllowedException",
    "message":"Operation is not allowed for role with id 'my-role'."
  }
}

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:

login - String
email - String
first_name - String
last_name - 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
last_login_date - Date

Url

POST https://hostname:port/dw/data/v18_6/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/v18_6/roles/my-role/user_search HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.62ed5
Accept: application/json

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

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

{
    "_v": "18.6",
    "_type": "user_search_result",
    "count": 1,
    "hits": [
        {
            "_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"
        }
    ],
    "query": {
        "text_query": {
            "_type": "text_query",
            "fields": [
                "login"
            ],
            "search_phrase": "Dude"
        }
    },
    "select": "(**)",
    "start": 0,
    "total": 1
}

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/v18_6/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
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/v18_6/roles/my-role/users?select=(**) HTTP/1.1
Host: example.com
Authorization: Bearer b6104653-d53c-4175-a23d-52f118.62ed5
Accept: application/json

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

{
    "_v": "18.6",
    "_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/v18_6/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
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:
PUT /s/-/dw/data/v18_6/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 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":"18.6",
  "fault":{
    "type":"RoleNotFoundException",
    "message":"No access role with id 'my-role' 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":"18.6",
  "fault":{
    "type":"UserNotFoundException",
    "message":"No user with login 'my-role' found."
  }
}

Unassign User to Access Role

Action to unassign a user to an access role

Url

DELETE https://hostname:port/dw/data/v18_6/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/v18_6/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 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":"18.6",
  "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":"18.6",
  "fault":{
    "type":"RoleNotFoundException",
    "message":"No access role with id 'my-role' 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":"18.6",
  "fault":{
    "type":"UserNotFoundException",
    "message":"No user with login 'my-role' found."
  }
}

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.