Patch User Roles

1 min

PATCH

https://api.upstartcommerce.com/v1/users/user-roles

This endpoint allows for an admin to add roles to all specified users. It may be useful when a new site is added to a tenant, and all existing users' permissions have to be updated accordingly. Note that this endpoint can only add roles, not modify or delete existing roles.

Authorized system roles:

system.admin
user.mgmt

Body Parameters

bodyUserRolesRequestrequired
Description
The users to update and the role assignments to apply to them.
- userIdsstring[]required
  Description
  A list of user ids.
- userRolesUserRolesrequired
  Example
```
{
  "tenant-name-1": {
    "roleIds": [
      "catalog.mgmt"
    ],
    "sites": {
      "example-site-name-1": {
        "roleIds": [
          "order.mgmt"
        ]
      },
      "example-site-name-2": {
        "roleIds": [
          "order.mgmt"
        ]
      }
    }
  },
  "tenant-name-2": {
    "roleIds": [
      "user.mgmt"
    ],
    "sites": {
      "example-site-name-1": {
        "roleIds": []
      },
      "example-site-name-2": {
        "roleIds": [
          "inventory.mgmt"
        ]
      }
    }
  }
}
```
  Description
  A map indexed by a tenant name listing all tenant-level roles and site-level roles. For example: { "tenant1" : { "roleIds" : ["some.role1","some.role2"], sites: { "site1": { "roleIds": ["some.role3","some.role4"] }, "site2": { "roleIds": ["some.role4","some.role6"] } } }, "tenant2" : { "roleIds" : ["some.other.role1","some.other.role2"], sites: { "site1": { "roleIds": ["some.other.role3","some.other.role4"] }, "site2": { "roleIds": ["some.other.role5","some.other.role6"] } } } }

Responses

200All users' roles have been successfully updated.

400The request contained information that the server was unable to process. Appropriate errors are provided in the response body.

ValidationErrorResponse
Description
Details of a request that failed validation.
- namestringrequired
- codestringrequired
- detailstring[]required
- reasonstring

401The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.

UnauthorizedError
Description
Credentials are missing, expired or insufficient (HTTP 401).
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

403

An update to this resource requires the if-match and if-unmodified-since headers to be sent in order to process the request.

ForbiddenError
Description
The request is understood but refused (HTTP 403).
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

404The requested resource was not found in the NoChannel system.

NotFoundError
Description
The addressed resource does not exist (HTTP 404).
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

409The request conflicts with the current state of the resource.

ConflictError
Description
The request conflicts with existing state (HTTP 409).
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

500Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.

InternalServerError
Description
The request failed for an unexpected reason (HTTP 500).
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

curl

curl --request PATCH \
     --url https://api.upstartcommerce.com/v1/users/user-roles \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "userIds": [],
     "userRoles": "{\"tenant-name-1\":{\"roleIds\":[\"catalog.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[\"order.mgmt\"]},\"example-site-name-2\":{\"roleIds\":[\"order.mgmt\"]}}},\"tenant-name-2\":{\"roleIds\":[\"user.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[]},\"example-site-name-2\":{\"roleIds\":[\"inventory.mgmt\"]}}}}"
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var raw = JSON.stringify({
   "userIds": [],
   "userRoles": "{\"tenant-name-1\":{\"roleIds\":[\"catalog.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[\"order.mgmt\"]},\"example-site-name-2\":{\"roleIds\":[\"order.mgmt\"]}}},\"tenant-name-2\":{\"roleIds\":[\"user.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[]},\"example-site-name-2\":{\"roleIds\":[\"inventory.mgmt\"]}}}}"
});

var requestOptions = {
   method: 'PATCH',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/v1/users/user-roles", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.upstartcommerce.com/v1/users/user-roles")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "userIds": [],
   "userRoles": "{\"tenant-name-1\":{\"roleIds\":[\"catalog.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[\"order.mgmt\"]},\"example-site-name-2\":{\"roleIds\":[\"order.mgmt\"]}}},\"tenant-name-2\":{\"roleIds\":[\"user.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[]},\"example-site-name-2\":{\"roleIds\":[\"inventory.mgmt\"]}}}}"
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.upstartcommerce.com/v1/users/user-roles"

payload = json.dumps({
   "userIds": [],
   "userRoles": "{\"tenant-name-1\":{\"roleIds\":[\"catalog.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[\"order.mgmt\"]},\"example-site-name-2\":{\"roleIds\":[\"order.mgmt\"]}}},\"tenant-name-2\":{\"roleIds\":[\"user.mgmt\"],\"sites\":{\"example-site-name-1\":{\"roleIds\":[]},\"example-site-name-2\":{\"roleIds\":[\"inventory.mgmt\"]}}}}"
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

200

// All users' roles have been successfully updated.

400

// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.
{
  "name": "",
  "code": "",
  "detail": [
    ""
  ],
  "reason": ""
}

401

// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

403

// An update to this resource requires the if-match and if-unmodified-since headers to be sent in order to process the request.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

404

// The requested resource was not found in the NoChannel system.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

409

// The request conflicts with the current state of the resource.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}

500

// Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}