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 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/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 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 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/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."
  }
}

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.

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.