Overview
The Permissions API allows platform administrators to:
- Create and manage global permissions
- List and search permissions
- Update permission details
- Delete unused permissions
Permissions define what actions users can perform globally across the platform. These are different from company-scoped roles and permissions.
Authentication
All endpoints require:
- Authentication using a Bearer token in the
Authorization header
- Platform admin privileges
Create Permission
curl -X POST https://api.example.com/api/permissions \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "COMPANY:CREATE",
"description": "Allows creating new companies",
"scope": "GLOBAL"
}'
Endpoint
Request Body
Permission key in format RESOURCE:ACTION (e.g., COMPANY:CREATE, USER:DELETE). Must be uppercase with underscores. Max 120 characters.
Human-readable description of what this permission allows (max 255 characters)
Permission scope. Options: GLOBAL or COMPANY. Defaults to COMPANY.
Response
Indicates if the request was successful
The created permission object
Unique identifier for the permission
Permission scope: GLOBAL or COMPANY
Usage statistics
Number of roles using this permission
Number of users with this permission granted globally
Response Example
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "COMPANY:CREATE",
"description": "Allows creating new companies",
"scope": "GLOBAL",
"_count": {
"roles": 0,
"userGlobalPermissions": 0
}
}
}
Error Responses
Invalid permission key format
{
"success": false,
"error": "Key must follow format RESOURCE:ACTION (e.g., COMPANY:CREATE)"
}
Permission key already exists
{
"success": false,
"error": "Permission key already exists"
}
List Permissions
curl -X GET "https://api.example.com/api/permissions?page=1&limit=50&scope=GLOBAL" \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
Query Parameters
Page number for pagination (min: 1)
Number of items per page (min: 1, max: 100)
Search term to filter by key or description (case-insensitive)
Filter by scope: GLOBAL or COMPANY
Response
Indicates if the request was successful
Array of permission objects
Response Example
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "COMPANY:CREATE",
"description": "Allows creating new companies",
"scope": "GLOBAL",
"_count": {
"roles": 2,
"userGlobalPermissions": 5
}
},
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"key": "USER:DELETE",
"description": "Allows deleting user accounts",
"scope": "GLOBAL",
"_count": {
"roles": 1,
"userGlobalPermissions": 2
}
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 2,
"totalPages": 1
}
}
Get All Permissions
curl -X GET https://api.example.com/api/permissions/all \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
Response
Indicates if the request was successful
Array of all permission objects (simplified, without count data)
Response Example
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "COMPANY:CREATE",
"description": "Allows creating new companies",
"scope": "GLOBAL"
},
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"key": "USER:DELETE",
"description": "Allows deleting user accounts",
"scope": "GLOBAL"
}
]
}
Get Permission by ID
curl -X GET https://api.example.com/api/permissions/{id} \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
GET /api/permissions/{id}
Path Parameters
The unique identifier of the permission
Response
Indicates if the request was successful
Response Example
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "COMPANY:CREATE",
"description": "Allows creating new companies",
"scope": "GLOBAL",
"_count": {
"roles": 2,
"userGlobalPermissions": 5
}
}
}
Error Responses
{
"success": false,
"error": "Permission not found"
}
Update Permission
curl -X PATCH https://api.example.com/api/permissions/{id} \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"description": "Updated description for this permission"
}'
Endpoint
PATCH /api/permissions/{id}
Path Parameters
The unique identifier of the permission to update
Request Body
New permission key (must follow RESOURCE:ACTION format)
New description (max 255 characters)
New scope: GLOBAL or COMPANY
Response
Indicates if the request was successful
The updated permission object
Response Example
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"key": "COMPANY:CREATE",
"description": "Updated description for this permission",
"scope": "GLOBAL",
"_count": {
"roles": 2,
"userGlobalPermissions": 5
}
}
}
Error Responses
New permission key already exists
{
"success": false,
"error": "Permission key already exists"
}
Delete Permission
curl -X DELETE https://api.example.com/api/permissions/{id} \
-H "Authorization: Bearer YOUR_TOKEN"
Endpoint
DELETE /api/permissions/{id}
Path Parameters
The unique identifier of the permission to delete
Response
Indicates if the request was successful
Response Example
{
"success": true,
"message": "Permission deleted successfully"
}
Error Responses
Permission is currently in use and cannot be deleted
{
"success": false,
"error": "Cannot delete permission. It is assigned to 2 roles and 5 users."
}
{
"success": false,
"error": "Permission not found"
}
Permission Scopes
Permissions can have two scopes:
GLOBAL
Global permissions apply across the entire platform and are not tied to any specific company. Examples:
COMPANY:CREATE - Create new companiesUSER:DELETE - Delete user accountsPLATFORM:ADMIN - Full platform administration
COMPANY
Company-scoped permissions are managed within individual companies and assigned through roles. Examples:
MEMBER:INVITE - Invite members to a companyPROJECT:CREATE - Create projects within a companyTIMESHEET:APPROVE - Approve timesheets
Global permissions can be requested by users through the Permission Requests API and must be approved by platform administrators.