Skip to main content

​
Overview

Role and permission actions provide CRUD operations for roles, permissions, and their relationships. All functions are located in src/app/actions/roles.ts.

​
Role Operations

​
getRolesService

Retrieves a list of roles with optional filtering.
​
queryParams
object
Query parameters for filtering
​
name
string
Filter roles by name
​
data
Role[]
Array of role objects
import { getRolesService } from "@/app/actions";

export default async function RolesPage() {
  const roles = await getRolesService();

  return <RoleList roles={roles} />;
}
On permission errors (403) or network issues, this function returns an empty array instead of throwing an error.

​
getSingleRoleService

Retrieves a single role by ID.
​
id
string
required
Unique role identifier
​
data
Role
Complete role object with permissions
import { getSingleRoleService } from "@/app/actions";

const role = await getSingleRoleService("role-123");

console.log(role.name);
console.log(role.description);
console.log(role.permissions.length);

​
getRoleService

Retrieves a single role by ID (alternative to getSingleRoleService).
​
id
string
required
Unique role identifier
​
data
Role
Complete role object
import { getRoleService } from "@/app/actions";

const role = await getRoleService("role-123");
This function provides the same functionality as getSingleRoleService. Use either based on your preference.

​
addRoleService

Creates a new role.
​
payload
AddRolePayload
required
Role creation data
​
name
string
required
Role name (minimum 1 character)
​
description
string
required
Role description (minimum 1 character)
​
active
boolean
required
Whether the role is active
​
response
ApiResponse
Standard API response object
​
success
boolean
Whether the operation succeeded
​
statusCode
number
HTTP status code
​
message
string
Response message
​
data
object
Created role data
"use client";
import { addRoleService } from "@/app/actions";
import { AddRolePayload } from "@/schema";
import { toast } from "sonner";

export function AddRoleForm() {
  const handleSubmit = async (data: AddRolePayload) => {
    const response = await addRoleService(data);
    
    if (response.success) {
      toast.success("Role added successfully");
      router.push("/roles");
    } else {
      toast.error(response.message || "Failed to add role");
    }
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

​
editRoleService

Updates an existing role.
​
id
string
required
Role ID to update
​
payload
EditRolePayload
required
Updated role data (same structure as AddRolePayload)
​
response
ApiResponse
Standard API response object
import { editRoleService } from "@/app/actions";
import { toast } from "sonner";

const handleUpdate = async (roleId: string, data: EditRolePayload) => {
  const response = await editRoleService(roleId, data);
  
  if (response.success) {
    toast.success("Role updated successfully");
  } else {
    toast.error(response.message);
  }
};

​
toggleRoleActiveStatusService

Toggles the active status of a role.
​
id
string
required
Role ID to toggle
​
response
ApiResponse
Standard API response object
import { toggleRoleActiveStatusService } from "@/app/actions";
import { toast } from "sonner";

const handleToggle = async (roleId: string) => {
  const response = await toggleRoleActiveStatusService(roleId);
  
  if (response.success) {
    toast.success("Role status updated successfully");
  } else {
    toast.error(response.message);
  }
};

​
deleteRoleService

Deletes a role.
​
id
string
required
Role ID to delete
​
response
ApiResponse
Standard API response object
import { deleteRoleService } from "@/app/actions";
import { toast } from "sonner";

const handleDelete = async (roleId: string) => {
  const response = await deleteRoleService(roleId);
  
  if (response.success) {
    toast.success("Role deleted successfully");
  } else {
    toast.error(response.message);
  }
};
Deleting a role that is assigned to users may cause issues. Consider deactivating roles instead.

​
getUsersByRoleIdService

Retrieves all users assigned to a specific role.
​
id
string
required
Role ID
​
data
unknown[]
Array of user objects assigned to the role
import { getUsersByRoleIdService } from "@/app/actions";

const users = await getUsersByRoleIdService("role-123");

console.log(`${users.length} users have this role`);
Returns an empty array on errors instead of throwing, allowing graceful error handling.

​
Permission Operations

​
getPermissionsService

Retrieves a list of all available permissions.
​
data
Permission[]
Array of permission objects
import { getPermissionsService } from "@/app/actions";

export default async function PermissionsPage() {
  const permissions = await getPermissionsService();

  return <PermissionList permissions={permissions} />;
}
Fetches up to 100 permissions (page=1, limit=100). Returns empty array on permission errors (403) or network issues.

​
getPermissionsByRoleIdService

Retrieves all permissions assigned to a specific role.
​
roleId
string
required
Role ID
​
data
Permission[]
Array of permission objects assigned to the role
import { getPermissionsByRoleIdService } from "@/app/actions";

const permissions = await getPermissionsByRoleIdService("role-123");

console.log(`Role has ${permissions.length} permissions`);
permissions.forEach(p => {
  console.log(`${p.action} on ${p.resource}`);
});
Handles both API response formats: permissions array directly or nested within a role object. Returns empty array on errors.

​
addPermissionsToRoleService

Assigns permissions to a role.
​
roleId
string
required
Role ID to assign permissions to
​
permission_id
string[]
required
Array of permission IDs to assign
​
response
ApiResponse
Standard API response object
import { addPermissionsToRoleService } from "@/app/actions";
import { toast } from "sonner";

const handleAddPermissions = async (
  roleId: string,
  permissionIds: string[]
) => {
  const response = await addPermissionsToRoleService(
    roleId,
    permissionIds
  );
  
  if (response.success) {
    toast.success("Permissions added successfully");
  } else {
    toast.error(response.message);
  }
};

​
addPermissionService

Creates a new permission.
​
payload
AddPermissionPayload
required
Permission creation data
​
name
string
required
Permission name (minimum 1 character)
​
resource
string
required
Resource the permission applies to (minimum 1 character)
​
action
string
required
Action the permission allows (minimum 1 character)
​
response
ApiResponse
Standard API response object
import { addPermissionService } from "@/app/actions";
import { AddPermissionPayload } from "@/schema";
import { toast } from "sonner";

const handleSubmit = async (data: AddPermissionPayload) => {
  const response = await addPermissionService(data);
  
  if (response.success) {
    toast.success("Permission added successfully");
  } else {
    toast.error(response.message);
  }
};

​
Type Definitions

​
Role

interface Role {
  id: string;
  name: string;
  permissions: Permission[];
  level: number;
  description: string;
  created_at: number;
  created_at_datetime: string;
  active: boolean;
}

​
Permission

interface Permission {
  id: string;
  name: string;
  resource: string;
  action: string;
  created_at: number;
  created_at_datetime: string;
}
Import types and schemas: 
import {
  getRolesService,
  getPermissionsService,
  addRoleService,
  addPermissionService,
} from "@/app/actions";
import {
  AddRolePayload,
  EditRolePayload,
  AddPermissionPayload,
  ADD_ROLE_SCHEMA,
  EDIT_ROLE_SCHEMA,
  ADD_PERMISSION_SCHEMA,
} from "@/schema";
import { ApiResponse } from "@/app/actions";

Build docs developers (and LLMs) love

Get started for freeTalk to us