Get Users by Roles

1 min

POST

https://api.upstartcommerce.com/v1/users/list-by-roles

This endpoint returns all users having the specified role. The filter works as "any" -- a user will be returned if they have at least one role from the request.

Body Parameters

bodystring[]required
Description
A list of role ids.

Responses

200A list of users.

UserSummary[]
Description
Summary of a user: identity, contact details, tenant, role assignments and lock state.
- emailAddressstring<email>required
  Example
  [email protected]
  Description
  The user's email address.
  Format
  email
- idstring<UUID>required
  Description
  Unique identifier for this user. If it is not provided a UUID will be allocated.
  Format
  UUID
- lockbooleanrequired
  Description
  This indicates whether the user is currently locked out of the system.
  Default
  false
- loginstringrequired
  Description
  The login (username) that is being requested for the user.
- namestringrequired
  Description
  First, last, and (optional) middle names of the user.
- userRolesUserRoles
  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"] } } } }
- phoneNumberstring
  Description
  The contact phone number for this user.
- registrationDatestring<date-time>
  Description
  The date/time on which this user was created.
  Format
  date-time
- tenantstringrequired
  Description
  This is the id of the tenant that this user is associated with.
- isPasswordAllowedboolean
  Description
  Indicates if the user is allowed to set a password or must use social authentication.

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 POST \
     --url https://api.upstartcommerce.com/v1/users/list-by-roles \
     --header 'accept: application/json'

javascript

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

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/v1/users/list-by-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/list-by-roles")

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

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"

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

python

import requests
import json

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

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

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

print(response.text)

200

// A list of users.
[
  {
    "emailAddress": "[email protected]",
    "id": "",
    "lock": false,
    "login": "",
    "name": "",
    "userRoles": {},
    "phoneNumber": "",
    "registrationDate": "",
    "tenant": "",
    "isPasswordAllowed": false
  }
]

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": ""
}