OVERVIEW
Security Roles allow you to specify what Users are allowed to do.
The figure below shows how Security Roles interact with Resources in the User Manager and Company Tree APIs.
To learn more about Users, Security Roles and Permissions see User Manager.
ENDPOINTS
Sandbox: https://usermanagerdemo.iqmetrix.net/v1
Production: https://usermanager.iqmetrix.net/v1
RESOURCES
SecurityRole
A SecurityRole represents the relationship between a User and a set of Permissions. SecurityRoles allow you create custom groups that can hold Permissions
{
"Id": 316,
"Name": "Store Manager"
}
Name | Description | |
---|---|---|
Id (Integer ) |
Identifier | |
Name (String ) |
Name | |
SecurityModelVersion (Integer ) |
Reserved for internal use |
AssignedRole
An AssignedRole represents the relationship between a User, SecurityRole and Entity.
{
"Id": 6548,
"EntityId": 14202,
"SecurityRoleId": 316,
"UserId": 2576
}
Name | Description |
---|---|
Id (Integer ) |
Identifier |
EntityId (Integer ) |
Identifier of a CompanyTreeNode |
SecurityRoleId (Integer ) |
Identifier of a SecurityRole |
UserId (Integer ) |
Identifier of a User |
Permission
Permissions are the building blocks of SecurityRoles and represent the ability to perform an action within iQmetrix APIs.
- Assigning a Permission to a Security Role always grants an action
- A Permission will never overrule another Permission
- When
IsAssignable
is set tofalse
, the Permission is Restricted by iQmetrix. If you require access to a Restricted Permission, contact Support
{
"Id": 101,
"Name": "Edit Products",
"Category": "Products",
"Code": "editproducts",
"Description": "Enables the user to create, update and archive their private products and retailer revisions.",
"ParentPermissionId": 99
}
Name | Description |
---|---|
Id (Integer ) |
Identifier |
Name (String ) |
Descriptive name |
Category (String ) |
This field is used internally to group Permissions by how they impact the iQmetrix ecosystem |
Code (String ) |
Unique, system generated name used for sorting Permissions |
Description (String ) |
Describes the function of the Permission |
ParentPermissionId (Integer ) |
Identifier of a similar Permission, used for organizing Permissions into groups |
REQUESTS
GET All Permissions for an Entity
This request will return all Permissions within the SecurityRoles belonging to the specified Entity.
Request
GET /Entities({EntityId})/Permissions
Example Request
GET /Entities(14146)/Permissions
Authorization: Bearer (Access Token)
Accept: application/json
curl -X GET "https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/Permissions" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json"
static IRestResponse GettingAllPermissionsForAnEntity()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/Permissions");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
return client.Execute(request);
}
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse GettingAllPermissionsForAnEntity() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpGet request = new HttpGet("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/Permissions");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.get 'https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/Permissions', {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
}
puts response
URI Parameters
EntityId
(Required) - Identifier of a CompanyTreeNode
Response Parameters
Example Response
HTTP 200 Content-Type: application/json
[
{
"Id": 101,
"Name": "Edit Products",
"Category": "Products",
"Code": "editproducts",
"Description": "Enables the user to create, update and archive their private products and retailer revisions.",
"IsAssignable": true,
"ParentPermissionId": 99
}
]
Id
(Integer)Name
(String)Category
(String)Code
(String)Description
(String)IsAssignable
(Boolean)ParentPermissionId
(Integer)
POST a Security Role
Request
POST /Entities({EntityId})/SecurityRoles
Example Request
POST /Entities(14146)/SecurityRoles
Authorization: Bearer (Access Token)
Accept: application/json
Content-Type: application/json
{
"Name": "Store Manager"
}
curl -X POST "https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
"Name": "Store Manager"
}'
static IRestResponse CreatingASecurityRole()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\"Name\":\"Store Manager\"}", ParameterType.RequestBody);
return client.Execute(request);
}
import org.apache.http.entity.StringEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse CreatingASecurityRole() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpPost request = new HttpPost("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
request.addHeader("Content-Type", "application/json");
StringEntity body = new StringEntity("{\"Name\":\"Store Manager\"}");
request.setEntity(body);
return httpClient.execute(request);
}
require 'rest-client'
body = "{\"Name\":\"Store Manager\"}";
response = RestClient.post 'https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles', body, {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
:'Content-Type' => 'application/json',
}
puts response
URI Parameters
EntityId
(Required) - Identifier of a CompanyTreeNode
Request Parameters
Name
(Required) - A descriptive name, must be unique within the Company
Response Parameters
Example Response
HTTP 201 Content-Type: application/json
{
"Id": 316,
"Name": "Store Manager"
}
GET All Security Roles for an Entity
Request
GET /Entities({EntityId})/SecurityRoles
Example Request
GET /Entities(14146)/SecurityRoles
Authorization: Bearer (Access Token)
Accept: application/json
curl -X GET "https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json"
static IRestResponse GettingAllSecurityRolesForAnEntity()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
return client.Execute(request);
}
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse GettingAllSecurityRolesForAnEntity() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpGet request = new HttpGet("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.get 'https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles', {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
}
puts response
URI Parameters
EntityId
(Required) - Identifier of a CompanyTreeNode
Response Parameters
Example Response
HTTP 200 Content-Type: application/json
[
{
"Id": 316,
"Name": "Store Manager"
}
]
Array[SecurityRole]
DELETE a Security Role
Deletes a security role. If the role is assigned to no users or inactive users, it will be removed. A Security Role assigned to active Users cannot be deleted.
Request
DELETE /Entities({EntityId})/SecurityRoles({SecurityRoleId})
Example Request
DELETE /Entities(14146)/SecurityRoles(316)
Authorization: Bearer (Access Token)
Accept: application/json
curl -X DELETE "https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json"
static IRestResponse DeletingASecurityRole()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
return client.Execute(request);
}
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse DeletingASecurityRole() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpDelete request = new HttpDelete("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.delete 'https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)', {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
}
puts response
URI Parameters
EntityId
(Required) - Identifier of a CompanyTreeNodeSecurityRoleId
(Required) - Identifier of a SecurityRole
Response Parameters
Example Response
HTTP 204
Enabling a Permission for a Security Role
Request
PUT /Entities({EntityId})/SecurityRoles({SecurityRoleId})/Permissions({PermissionId})
Example Request
PUT /Entities(14146)/SecurityRoles(316)/Permissions(101)
Authorization: Bearer (Access Token)
Accept: application/json
Content-Type: application/json
curl -X PUT "https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json" -H "Content-Type: application/json"
static IRestResponse EnablingAPermissionForASecurityRole()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
return client.Execute(request);
}
import org.apache.http.entity.StringEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse EnablingAPermissionForASecurityRole() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpPut request = new HttpPut("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
request.addHeader("Content-Type", "application/json");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.put 'https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)', body, {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
:'Content-Type' => 'application/json',
}
puts response
URI Parameters
EntityId
(Required) - Identifier of a CompanyTreeNodeSecurityRoleId
(Required) - Identifier of a SecurityRolePermissionId
(Required) - Identifier of a Permission
Response Parameters
Example Response
HTTP 204 Content-Type: application/json
Disabling a Permission for a Security Role
Request
DELETE /Entities({EntityId})/SecurityRoles({SecurityRoleId})/Permissions({PermissionId})
Example Request
DELETE /Entities(14146)/SecurityRoles(316)/Permissions(101)
Authorization: Bearer (Access Token)
curl -X DELETE "https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)" -H "Authorization: Bearer (Access Token)"
static IRestResponse DisablingAPermissionForASecurityRole()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer (Access Token)");
return client.Execute(request);
}
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse DisablingAPermissionForASecurityRole() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpDelete request = new HttpDelete("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)");
request.addHeader("Authorization", "Bearer (Access Token)");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.delete 'https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions(101)', {
:'Authorization' => 'Bearer (Access Token)',
}
puts response
URI Parameters
EntityId
(Required) - Identifier of a CompanyTreeNodeSecurityRoleId
(Required) - Identifier of a SecurityRolePermissionId
(Required) - Identifier of a Permission
Response Parameters
Example Response
HTTP 204 Content-Type: application/json
GET Permissions for a Security Role
Request
GET /Entities({EntityId})/SecurityRoles({SecurityRoleId})/Permissions
Example Request
GET /Entities(14146)/SecurityRoles(316)/Permissions
Authorization: Bearer (Access Token)
Accept: application/json
curl -X GET "https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json"
static IRestResponse GettingPermissionsForASecurityRole()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
return client.Execute(request);
}
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse GettingPermissionsForASecurityRole() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpGet request = new HttpGet("https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.get 'https://usermanagerdemo.iqmetrix.net/v1/Entities(14146)/SecurityRoles(316)/Permissions', {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
}
puts response
URI Parameters
EntityId
(Required) - Identifier of a CompanyTreeNodeSecurityRoleId
(Required) - Identifier of a SecurityRole
Response Parameters
Example Response
HTTP 200 Content-Type: application/json
[
{
"Id": 101,
"Name": "Edit Products",
"Category": "Products",
"Code": "editproducts",
"Description": "Enables the user to create, update and archive their private products and retailer revisions.",
"ParentPermissionId": 99
}
]
Array[Permission]
Assigning a Security Role to a User
If the User is assigned a SecurityRole they already have, the result will be a HTTP 200
with the AssignedRole, the same response as assigning a new SecurityRole to a User.
Request
POST /Users({UserId})/AssignedRoles
Example Request
POST /Users(2576)/AssignedRoles
Authorization: Bearer (Access Token)
Accept: application/json
Content-Type: application/json
{
"EntityId": 14202,
"SecurityRoleId": 316
}
curl -X POST "https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json" -H "Content-Type: application/json" -d '{
"EntityId": 14202,
"SecurityRoleId": 316
}'
static IRestResponse AssigningASecurityRoleToAUser()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\"EntityId\":14202,\"SecurityRoleId\":316}", ParameterType.RequestBody);
return client.Execute(request);
}
import org.apache.http.entity.StringEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse AssigningASecurityRoleToAUser() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpPost request = new HttpPost("https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
request.addHeader("Content-Type", "application/json");
StringEntity body = new StringEntity("{\"EntityId\":14202,\"SecurityRoleId\":316}");
request.setEntity(body);
return httpClient.execute(request);
}
require 'rest-client'
body = "{\"EntityId\":14202,\"SecurityRoleId\":316}";
response = RestClient.post 'https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles', body, {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
:'Content-Type' => 'application/json',
}
puts response
URI Parameters
UserId
(Required) - Identifier of a User
Request Parameters
EntityId
(Required) - Identifier of a CompanyTreeNodeSecurityRoleId
(Required)
Response Parameters
Example Response
HTTP 201 Content-Type: application/json
{
"Id": 6548,
"EntityId": 14202,
"SecurityRoleId": 316,
"UserId": 2576
}
GET Assigned Roles for a User
Request
GET /Users({UserId})/AssignedRoles
Example Request
GET /Users(2576)/AssignedRoles
Authorization: Bearer (Access Token)
Accept: application/json
curl -X GET "https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles" -H "Authorization: Bearer (Access Token)" -H "Accept: application/json"
static IRestResponse GettingAssignedRolesForAUser()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer (Access Token)");
request.AddHeader("Accept", "application/json");
return client.Execute(request);
}
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse GettingAssignedRolesForAUser() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpGet request = new HttpGet("https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles");
request.addHeader("Authorization", "Bearer (Access Token)");
request.addHeader("Accept", "application/json");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.get 'https://usermanagerdemo.iqmetrix.net/v1/Users(2576)/AssignedRoles', {
:'Authorization' => 'Bearer (Access Token)',
:'Accept' => 'application/json',
}
puts response
URI Parameters
UserId
(Required) - Identifier of a User
Response Parameters
Example Response
HTTP 200 Content-Type: application/json
[
{
"Id": 6548,
"EntityId": 14202,
"SecurityRoleId": 316,
"UserId": 2576
}
]
Array[AssignedRole]
Unassigning a Security Role from a User
Request
DELETE /Users({UserId})/AssignedRoles({SecurityRoleId})
Example Request
DELETE /Users(2572)/AssignedRoles(316)
Authorization: Bearer (Access Token)
curl -X DELETE "https://usermanagerdemo.iqmetrix.net/v1/Users(2572)/AssignedRoles(316)" -H "Authorization: Bearer (Access Token)"
static IRestResponse UnassigningASecurityRoleFromAUser()
{
var client = new RestClient("https://usermanagerdemo.iqmetrix.net/v1/Users(2572)/AssignedRoles(316)");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer (Access Token)");
return client.Execute(request);
}
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.IOException;
public static CloseableHttpResponse UnassigningASecurityRoleFromAUser() throws IOException {
CloseableHttpClient httpClient = HttpClients.createDefault();
HttpDelete request = new HttpDelete("https://usermanagerdemo.iqmetrix.net/v1/Users(2572)/AssignedRoles(316)");
request.addHeader("Authorization", "Bearer (Access Token)");
return httpClient.execute(request);
}
require 'rest-client'
response = RestClient.delete 'https://usermanagerdemo.iqmetrix.net/v1/Users(2572)/AssignedRoles(316)', {
:'Authorization' => 'Bearer (Access Token)',
}
puts response
URI Parameters
UserId
(Required) - Identifier of a UserSecurityRoleId
(Required) - Identifier of a SecurityRole
Response Parameters
Example Response
HTTP 204 Content-Type: application/json
ERRORS
HTTP Status Code | Description | How to Resolve |
---|---|---|
HTTP 400 |
The field {x} is a required field but was not found in the request |
Ensure all required parameters are included |
HTTP 400 |
Expected {x} to contain {y} but found {z} |
Ensure parameters that are in both Request URI and body match |
HTTP 403 |
Security role assigned to active users |
Ensure Security Role is not assigned to any active users |
HTTP 404 |
{x} not found |
Ensure URI parameters are correct |
HTTP 409 |
The SecurityRole name {x} already exists for entity {y} |
SecurityRole names must be unique across the Company |