Overview
The Roles & Permissions API provides endpoints for managing role-based access control (RBAC). Permissions are granular authorities (e.g., user:read, vehicle:create) that are assigned to roles, which are then assigned to users.
Base URL
https://your-domain.com/v1
List All Roles
Retrieves all roles defined in the system.
Authentication: Required
Authorization: user:read permission
Response
[
{
"id": 1,
"name": "ADMIN",
"description": "Administrator role with full permissions",
"permissions": [
{
"id": 1,
"name": "user:read",
"description": "Read user information"
},
{
"id": 2,
"name": "user:create",
"description": "Create new users"
}
]
},
{
"id": 2,
"name": "USER",
"description": "Standard user role",
"permissions": [
{
"id": 1,
"name": "user:read",
"description": "Read user information"
}
]
}
]
Status Codes
200 OK - Roles retrieved successfully401 Unauthorized - Not authenticated
Example
curl -X GET https://your-domain.com/v1/roles \
-H "Authorization: Bearer YOUR_TOKEN"
Add Permissions to Role
POST /v1/roles/{id}/add-permissions
user:create or user:update permission
Path Parameters
Request Body
Array of permission names to add
[
"vehicle:read",
"vehicle:create"
]
Response
{
"id": 2,
"name": "USER",
"description": "Standard user role",
"permissions": [
{
"id": 1,
"name": "user:read",
"description": "Read user information"
},
{
"id": 5,
"name": "vehicle:read",
"description": "Read vehicle information"
},
{
"id": 6,
"name": "vehicle:create",
"description": "Create new vehicles"
}
]
}
Status Codes
200 OK - Permissions added successfully401 Unauthorized - Not authenticated403 Forbidden - Missing required permission404 Not Found - Role not found
Example
curl -X POST https://your-domain.com/v1/roles/2/add-permissions \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '["vehicle:read", "vehicle:create"]'
Replace Role Permissions
PUT /v1/roles/{id}/permissions
user:update permission
This operation completely replaces the role’s permissions. Use with caution.
Path Parameters
Request Body
Complete array of permission names for the role
[
"user:read",
"vehicle:read"
]
Response
{
"id": 2,
"name": "USER",
"description": "Standard user role",
"permissions": [
{
"id": 1,
"name": "user:read",
"description": "Read user information"
},
{
"id": 5,
"name": "vehicle:read",
"description": "Read vehicle information"
}
]
}
Status Codes
200 OK - Permissions updated successfully401 Unauthorized - Not authenticated403 Forbidden - Missing user:update permission404 Not Found - Role not found
Example
curl -X PUT https://your-domain.com/v1/roles/2/permissions \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '["user:read", "vehicle:read"]'
Remove Permissions from Role
DELETE /v1/roles/{id}/remove-permissions
user:delete permission
Path Parameters
Request Body
Array of permission names to remove
Response
{
"id": 2,
"name": "USER",
"description": "Standard user role",
"permissions": [
{
"id": 1,
"name": "user:read",
"description": "Read user information"
},
{
"id": 5,
"name": "vehicle:read",
"description": "Read vehicle information"
}
]
}
Status Codes
200 OK - Permissions removed successfully401 Unauthorized - Not authenticated403 Forbidden - Missing user:delete permission404 Not Found - Role not found
Example
curl -X DELETE https://your-domain.com/v1/roles/2/remove-permissions \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '["vehicle:delete"]'
Permissions
List All Permissions
Retrieves the complete catalog of granular permissions available in the system.
Authentication: Required
Authorization: user:read permission
Response
[
{
"id": 1,
"name": "user:read",
"description": "Read user information"
},
{
"id": 2,
"name": "user:create",
"description": "Create new users"
},
{
"id": 3,
"name": "user:update",
"description": "Update user information"
},
{
"id": 4,
"name": "user:delete",
"description": "Delete users"
},
{
"id": 5,
"name": "vehicle:read",
"description": "Read vehicle information"
},
{
"id": 6,
"name": "vehicle:create",
"description": "Create new vehicles"
},
{
"id": 7,
"name": "vehicle:update",
"description": "Update vehicle information"
},
{
"id": 8,
"name": "vehicle:delete",
"description": "Delete vehicles"
},
{
"id": 9,
"name": "client:read",
"description": "Read client information"
},
{
"id": 10,
"name": "client:create",
"description": "Create new clients"
},
{
"id": 11,
"name": "client:update",
"description": "Update client information"
},
{
"id": 12,
"name": "client:delete",
"description": "Delete clients"
},
{
"id": 13,
"name": "contract:read",
"description": "Read contract information"
},
{
"id": 14,
"name": "contract:create",
"description": "Create new contracts"
},
{
"id": 15,
"name": "contract:update",
"description": "Update contract information"
},
{
"id": 16,
"name": "contract:delete",
"description": "Delete contracts"
}
]
Status Codes
200 OK - Permissions retrieved successfully401 Unauthorized - Not authenticated
Example
curl -X GET https://your-domain.com/v1/permissions \
-H "Authorization: Bearer YOUR_TOKEN"
Permission Naming Convention
Permissions follow a consistent naming pattern: resource:action
Resource Types
user - User managementvehicle - Vehicle managementclient - Client management (persons and companies)contract - Purchase/sale contract managementperson - Individual person client operationscompany - Company client operations
Action Types
read - View/retrieve resource informationcreate - Create new resourcesupdate - Modify existing resourcesdelete - Remove resources
Examples
user:read - Permission to view user informationvehicle:create - Permission to add new vehiclescontract:update - Permission to modify contractsclient:delete - Permission to delete clients
Default Roles
SGIVU includes the following default roles:
Complete access to all system resources:
- All
user:* permissions
- All
vehicle:* permissions
- All
client:* permissions
- All
contract:* permissions
Standard user with read-only access:
user:readvehicle:readclient:readcontract:read
Sales personnel permissions:
client:* (all client operations)contract:* (all contract operations)vehicle:readuser:read
INVENTORY
Inventory management permissions:
vehicle:* (all vehicle operations)client:readuser:read
All endpoints require a valid JWT Bearer token:
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
rolesAndPermissions claim containing the required permissions for the endpoint.
Error Responses
403 Forbidden
{
"error": "forbidden",
"message": "User does not have required permission: user:update"
}
404 Not Found
{
"error": "not_found",
"message": "Role with ID 999 not found"
}