API Reference
Start typing to search…

Roles

Roles are collections of permissions that define what operations users can perform within the View system. They serve as an intermediate layer in the Role-Based Access Control (RBAC) system, allowing administrators to group related permissions together and assign them to users efficiently.

API Endpoints

Roles are managed via the Configuration server API at [http|https]://[hostname]:[port]/v1.0/tenants/[tenant-guid]/roles

Supported HTTP Methods: GET, HEAD, PUT, DELETE

Important: All role operations require administrator-level access tokens.

Role Object Structure

Role objects contain access control definitions that serve as containers for permissions. Here's the complete structure:

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "All permissions role",
    "Active": true,
    "IsProtected": true,
    "CreatedUtc": "2025-10-09T17:27:05.247203Z"
}

Field Descriptions

  • GUID (GUID): Globally unique identifier for the role object
  • TenantGUID (GUID): Globally unique identifier for the tenant
  • Name (string): Display name for the role
  • Active (boolean): Indicates whether the role is active and can be used
  • IsProtected (boolean): Indicates whether the role is protected from modification
  • CreatedUtc (datetime): UTC timestamp when the role was created

Role-Permission Relationships

Roles are linked to permissions through separate permission mapping objects managed via the Permission Maps API. The relationship between roles and permissions is established through:

  • Permission Maps: Separate objects that link roles to specific permissions
  • User-Role Mappings: Objects that assign roles to users
  • Role-Permission Mappings: Objects that associate permissions with roles

This separation allows for flexible permission management where roles can be created independently and then associated with permissions as needed.

Enumerate Roles

Retrieves a paginated list of all role objects in the system using GET /v2.0/tenants/[tenant-guid]/roles/. This endpoint provides comprehensive enumeration with pagination support for managing multiple roles.

Request Parameters

No additional parameters required beyond authentication.

curl --location 'http://localhost:8000/v2.0/tenants/00000000-0000-0000-0000-000000000000/roles/' \
--header 'Authorization: ••••••'
import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

const enumerateRole = async () => {
  try {
    const response = await api.Rbac.Role.enumerate();
    console.log(response, 'Role fetched successfully');
  } catch (err) {
    console.log('Error fetching Role:', err);
  }
};

enumerateRole();

Response

Returns a paginated enumeration result containing role objects:

{
    "Success": true,
    "Timestamp": {
        "Start": "2025-10-15T08:11:03.939814Z",
        "TotalMs": 7.6,
        "Messages": {}
    },
    "MaxResults": 1000,
    "Skip": 0,
    "IterationsRequired": 1,
    "EndOfResults": true,
    "TotalRecords": 1,
    "RecordsRemaining": 0,
    "Objects": [
        {
            "GUID": "00000000-0000-0000-0000-000000000000",
            "TenantGUID": "00000000-0000-0000-0000-000000000000",
            "Name": "All permissions role",
            "Active": true,
            "IsProtected": true,
            "CreatedUtc": "2025-10-09T17:27:05.247203Z"
        }
    ]
}

Read All Roles

Retrieves all role objects in a single request using GET /v1.0/tenants/[tenant-guid]/roles. This endpoint provides a simple way to get all roles without pagination.

Request Parameters

No additional parameters required beyond authentication.

curl --location 'http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/roles' \
--header 'Authorization: ••••••'
import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

const readAllRole = async () => {
  try {
    const response = await api.Rbac.Role.readAll();
    console.log(response, 'Role fetched successfully');
  } catch (err) {
    console.log('Error fetching Role:', err);
  }
};

readAllRole();

Response

Returns an array of all role objects:

[
    {
        "GUID": "00000000-0000-0000-0000-000000000000",
        "TenantGUID": "00000000-0000-0000-0000-000000000000",
        "Name": "All permissions role",
        "Active": true,
        "IsProtected": true,
        "CreatedUtc": "2025-10-09T17:27:05.247203Z"
    }
]

Read Role

Retrieves a specific role object by its GUID using GET /v1.0/tenants/[tenant-guid]/roles/[role-guid]. This endpoint allows you to get detailed information about a single role.

Request Parameters

  • role-guid (string, Path, Required): GUID of the role to retrieve
curl --location 'http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/roles/00000000-0000-0000-0000-000000000000' \
--header 'Authorization: ••••••'
import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

const readRole = async () => {
  try {
    const response = await api.Rbac.Role.read('00000000-0000-0000-0000-000000000000');
    console.log(response, 'Role fetched successfully');
  } catch (err) {
    console.log('Error fetching Role:', err);
  }
};

readRole();

Response

Returns the requested role object:

{
    "GUID": "00000000-0000-0000-0000-000000000000",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "All permissions role",
    "Active": true,
    "IsProtected": true,
    "CreatedUtc": "2025-10-09T17:27:05.247203Z"
}

Create Role

Creates a new role object using PUT /v1.0/tenants/[tenant-guid]/roles. This endpoint allows you to define new role definitions for your system.

Request Parameters

{ 
  Name: 'Test Role', 	
  Active: true
}
curl --location 'http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/roles' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "Name": "Document Manager Role"
}'
import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

const createRole = async () => {
  try {
    const response = await api.Rbac.Role.create({ Name: 'Test Role', Active: true });
    console.log(response, 'Role created successfully');
  } catch (err) {
    console.log('Error creating Role:', err);
  }
};

createRole();

Response

Returns the created role object with generated GUID and timestamps:

{
    "GUID": "11111111-1111-1111-1111-111111111111",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "Document Manager Role",
    "Active": true,
    "IsProtected": false,
    "CreatedUtc": "2025-10-09T17:27:05.247203Z"
}

Update Role

Updates an existing role object using PUT /v1.0/tenants/[tenant-guid]/roles/[role-guid]. This endpoint allows you to modify role definitions.

Request Parameters

{
    "GUID": "11111111-1111-1111-1111-111111111111",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "Senior Document Manager Role",
    "Active": true,
    "IsProtected": false
}
curl --location --request PUT 'http://view.homedns.org:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/roles/00000000-0000-0000-0000-000000000000' \
--header 'content-type: application/json' \
--header 'Authorization: ••••••' \
--data '{
	"Name": "Super duper user",
	"Active": true
}'
import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

const updateRole = async () => {
  try {
    const response = await api.Rbac.Role.update({
      GUID: '47531afe-359e-4e19-b3a8-e12fa7815d8e',
      TenantGUID: '00000000-0000-0000-0000-000000000000',
      Name: 'Test Role Updated',
      Active: true,
      IsProtected: false,
      CreatedUtc: '2025-10-15T06:04:41.821018Z',
    });
    console.log(response, 'Role updated successfully');
  } catch (err) {
    console.log('Error updating Role:', err);
  }
};

updateRole();

Response

Returns the updated role object:

{
    "GUID": "11111111-1111-1111-1111-111111111111",
    "TenantGUID": "00000000-0000-0000-0000-000000000000",
    "Name": "Senior Document Manager Role",
    "Active": true,
    "IsProtected": false,
    "CreatedUtc": "2025-10-09T17:27:05.247203Z"
}

Delete Role

Deletes a role object by its GUID using DELETE /v1.0/tenants/[tenant-guid]/roles/[role-guid]. This endpoint permanently removes the role from the system.

Request Parameters

  • role-guid (string, Path, Required): GUID of the role to delete
curl --location --request DELETE 'http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/roles/11111111-1111-1111-1111-111111111111' \
--header 'Authorization: ••••••'
import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

const deleteRole = async () => {
  try {
    const response = await api.Rbac.Role.delete('47531afe-359e-4e19-b3a8-e12fa7815d8e');
    console.log(response, 'Role deleted successfully');
  } catch (err) {
    console.log('Error deleting Role:', err);
  }
};

deleteRole();

Check Role Existence

Checks if a role exists by its GUID using HEAD /v1.0/tenants/[tenant-guid]/roles/[role-guid]. This endpoint allows you to verify role presence without retrieving the full object.

Request Parameters

  • role-guid (string, Path, Required): GUID of the role to check
curl --location --head 'http://localhost:8000/v1.0/tenants/00000000-0000-0000-0000-000000000000/roles/11111111-1111-1111-1111-111111111111' \
--header 'Authorization: ••••••'
import { ViewConfigurationSdk } from "view-sdk";

const api = new ViewConfigurationSdk(
  "http://localhost:8000/", //endpoint
  "default", //tenant Id
  "default" //access key
);

const existsRole = async () => {
  try {
    const response = await api.Rbac.Role.exists('47531afe-359e-4e19-b3a8-e12fa7815d8e');
    console.log(response, 'Role exists successfully');
  } catch (err) {
    console.log('Error checking Role existence:', err);
  }
};


existsRole();

Security Notes

  • Admin Access Required: All role operations require administrator-level authentication tokens
  • Protected Roles: Some system roles may be protected from modification or deletion
  • Permission Inheritance: Roles contain permission maps that define which permissions are associated with the role
  • User Assignment: Roles are typically assigned to users through user-to-role mappings
  • Cascading Effects: Deleting a role may affect users who have been assigned that role

Error Handling

All role operations may return standard HTTP error codes:

  • 400 Bad Request: Invalid request parameters or malformed data
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Insufficient permissions to perform the operation
  • 404 Not Found: Role with specified GUID does not exist
  • 409 Conflict: Role conflicts with existing system constraints
  • 500 Internal Server Error: Unexpected server error during processing

Best Practices

  • Descriptive Naming: Use clear, descriptive names for roles that indicate their purpose
  • Principle of Least Privilege: Create roles that grant only the minimum necessary permissions
  • Regular Auditing: Periodically review and audit role assignments and permissions
  • Testing: Test role configurations in a development environment before production deployment
  • Documentation: Maintain documentation of custom role definitions and their intended use
  • Permission Management: Regularly review and update the permissions associated with each role