Skip to main content

​
Overview

The Permissions API provides endpoints to create, manage, and assign permissions to roles. Permissions define fine-grained access control for specific actions and resources within the application.

​
Authentication

All Permissions endpoints require the Administrator role. You must include a valid JWT token in the Authorization header: 
Authorization: Bearer <your-token>

​
Base URL

/api/Permissions

​
Available Endpoints

​
Permission Management

MethodEndpointDescription
GET/api/PermissionsGet all permissions
GET/api/Permissions/{permissionId}Get a specific permission by ID
POST/api/PermissionsCreate a new permission
PUT/api/Permissions/{permissionId}Update an existing permission
DELETE/api/Permissions/{permissionId}Delete a permission

​
Permission Assignment

MethodEndpointDescription
GET/api/Permissions/role/{roleId}Get all permissions for a role
POST/api/Permissions/assignAssign a permission to a role
POST/api/Permissions/removeRemove a permission from a role

​
Permission Entity Structure

Permissions in the system have the following structure:
​
id
integer
required
Unique identifier for the permission
​
name
string
required
Unique name of the permission (e.g., “users.create”, “reports.view”)
​
description
string
Human-readable description of what the permission allows
​
module
string
required
Module or feature area this permission belongs to (e.g., “Users”, “Reports”, “Settings”)
​
isActive
boolean
required
Whether the permission is currently active and can be used
​
createdAt
string
required
ISO 8601 timestamp when the permission was created

​
Permission Naming Convention

Permissions follow a hierarchical naming convention: 
{module}.{action}
Examples:
  • users.create - Create users
  • users.read - View users
  • users.update - Update users
  • users.delete - Delete users
  • reports.view - View reports
  • reports.export - Export reports
  • settings.manage - Manage system settings

​
Example Response

{
  "id": 1,
  "name": "users.create",
  "description": "Allows creating new users in the system",
  "module": "Users",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Role-Permission Relationship

Permissions are assigned to roles through the RolePermission entity:
​
roleId
string
required
ID of the role
​
permissionId
integer
required
ID of the permission
​
assignedAt
string
required
ISO 8601 timestamp when the permission was assigned to the role
​
assignedBy
string
User ID of the administrator who assigned the permission

​
Filtering Permissions

The GET /api/Permissions endpoint supports filtering:
​
activeOnly
boolean
default:"false"
When set to true, returns only active permissions
Example: 
GET /api/Permissions?activeOnly=true

​
Permission Modules

Permissions are organized into modules for better management:
  • Users - User management permissions
  • Roles - Role management permissions
  • Permissions - Permission management permissions
  • Reports - Reporting and analytics permissions
  • Settings - System configuration permissions
  • Documents - Document management permissions
  • Audit - Audit log access permissions

​
Error Responses

All endpoints may return the following error responses:
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - User does not have Administrator role
  • 404 Not Found - Permission not found
  • 409 Conflict - Permission name already exists (for create)
  • 500 Internal Server Error - Server error

​
Best Practices

Only assign permissions that are necessary for a role’s function. Start with minimal permissions and add more as needed.
Permission names should clearly describe what they allow. Use the module.action convention for consistency.
Always provide clear descriptions for permissions so administrators understand what they control.
Periodically review role-permission assignments to ensure they’re still appropriate and remove unnecessary access.

​
Next Steps

Manage Permissions

Create, update, and delete permissions

Assign to Roles

Assign permissions to roles

Build docs developers (and LLMs) love

Get started for freeTalk to us