API Documentation

In-depth reference documentation for iQmetrix API's.

NAV

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.

Changes within the Security Roles API involve complex actions behind the scenes and are not always immediate.

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.

{
    "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

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
    }
]

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

Request Parameters

Response Parameters

Example Response

HTTP 201 Content-Type: application/json
{
    "Id": 316,
    "Name": "Store Manager"
}

SecurityRole

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

Response Parameters

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "Id": 316,
        "Name": "Store Manager"
    }
]

Array[SecurityRole]

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

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

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

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

Request Parameters

Response Parameters

Example Response

HTTP 201 Content-Type: application/json
{
    "Id": 6548,
    "EntityId": 14202,
    "SecurityRoleId": 316,
    "UserId": 2576
}

AssignedRole

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

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

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 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
Was this page helpful?