Overview The Permission Requests API allows users to:
Request global permissions from platform administrators
View their own permission requests
Update or cancel pending requests
Platform administrators can:
Review all permission requests
Approve or reject requests
Automatically grant permissions upon approval
Authentication All endpoints require authentication using a Bearer token in the Authorization header. Admin-specific endpoints require platform admin privileges.
Get Available Permissions curl -X GET https://api.example.com/api/permission-requests/available-permissions \ -H "Authorization: Bearer YOUR_TOKEN"
Retrieves all global permissions that can be requested.
Endpoint GET /api/permission-requests/available-permissions
Response Indicates if the request was successful
Array of available permission objects Permission unique identifier
Permission key (e.g., COMPANY:CREATE)
Permission scope (always GLOBAL for requestable permissions)
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:MANAGE" , "description" : "Allows managing user accounts" , "scope" : "GLOBAL" } ] }
Create Permission Request curl -X POST https://api.example.com/api/permission-requests \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "GLOBAL_PERMISSION", "requestedPermissionId": "550e8400-e29b-41d4-a716-446655440000", "reason": "I need this permission to create a new company for our team" }'
Creates a new permission request for review by platform administrators.
Endpoint POST /api/permission-requests
Request Body type
string
default: "GLOBAL_PERMISSION"
Request type. Currently supports: GLOBAL_PERMISSION, OTHER
UUID of the global permission being requested (required for GLOBAL_PERMISSION type)
Justification for why this permission is needed (max 1000 characters)
Response Indicates if the request was successful
The created permission request object Show Permission Request Object
Request unique identifier
User who created the request
Request type: GLOBAL_PERMISSION or OTHER
Current status: PENDING, APPROVED, REJECTED, or CANCELLED
ID of the requested permission
ID of admin who reviewed the request
ISO 8601 timestamp of review
ISO 8601 timestamp of creation
ISO 8601 timestamp of last update
Response Example { "success" : true , "data" : { "id" : "770e8400-e29b-41d4-a716-446655440000" , "userId" : "880e8400-e29b-41d4-a716-446655440001" , "type" : "GLOBAL_PERMISSION" , "status" : "PENDING" , "requestedPermissionId" : "550e8400-e29b-41d4-a716-446655440000" , "reason" : "I need this permission to create a new company for our team" , "reviewedBy" : null , "reviewedAt" : null , "reviewNotes" : null , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T10:30:00.000Z" , "user" : { "id" : "880e8400-e29b-41d4-a716-446655440001" , "email" : "[email protected] " , "fullName" : "John Doe" , "avatar" : "https://example.com/avatars/johndoe.png" }, "requestedPermission" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "COMPANY:CREATE" , "description" : "Allows creating new companies" , "scope" : "GLOBAL" } }, "message" : "Permission request submitted successfully. An admin will review it soon." }
Error Responses Invalid request (permission not found, already have permission, or pending request exists)
{ "success" : false , "error" : "You already have a pending request for this permission" }
Requested permission not found
{ "success" : false , "error" : "Requested permission not found" }
Get User’s Permission Requests curl -X GET "https://api.example.com/api/permission-requests?page=1&limit=20&status=PENDING" \ -H "Authorization: Bearer YOUR_TOKEN"
Retrieves the authenticated user’s own permission requests with pagination.
Endpoint GET /api/permission-requests
Query Parameters Items per page (min: 1, max: 100)
Filter by status: PENDING, APPROVED, REJECTED, or CANCELLED
Filter by type: GLOBAL_PERMISSION or OTHER
Response Indicates if the request was successful
Array of permission request objects
Response Example { "success" : true , "data" : [ { "id" : "770e8400-e29b-41d4-a716-446655440000" , "userId" : "880e8400-e29b-41d4-a716-446655440001" , "type" : "GLOBAL_PERMISSION" , "status" : "PENDING" , "requestedPermissionId" : "550e8400-e29b-41d4-a716-446655440000" , "reason" : "I need this permission to create a new company for our team" , "reviewedBy" : null , "reviewedAt" : null , "reviewNotes" : null , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T10:30:00.000Z" , "user" : { "id" : "880e8400-e29b-41d4-a716-446655440001" , "email" : "[email protected] " , "fullName" : "John Doe" , "avatar" : "https://example.com/avatars/johndoe.png" }, "requestedPermission" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "COMPANY:CREATE" , "description" : "Allows creating new companies" , "scope" : "GLOBAL" }, "reviewer" : null } ], "pagination" : { "page" : 1 , "limit" : 20 , "total" : 1 , "totalPages" : 1 } }
Get All Permission Requests (Admin) curl -X GET "https://api.example.com/api/permission-requests/admin/all?page=1&limit=20&status=PENDING" \ -H "Authorization: Bearer YOUR_TOKEN"
Retrieves all permission requests across all users. Requires platform admin privileges.
Endpoint GET /api/permission-requests/admin/all
Query Parameters Items per page (min: 1, max: 100)
Filter by status: PENDING, APPROVED, REJECTED, or CANCELLED
Filter by type: GLOBAL_PERMISSION or OTHER
Response Same structure as “Get User’s Permission Requests”, but includes requests from all users.
Get Permission Request by ID curl -X GET https://api.example.com/api/permission-requests/{id} \ -H "Authorization: Bearer YOUR_TOKEN"
Retrieves a specific permission request by ID. Users can only view their own requests unless they are platform admins.
Endpoint GET /api/permission-requests/{id}
Path Parameters The unique identifier of the permission request
Response Indicates if the request was successful
The permission request object
Response Example { "success" : true , "data" : { "id" : "770e8400-e29b-41d4-a716-446655440000" , "userId" : "880e8400-e29b-41d4-a716-446655440001" , "type" : "GLOBAL_PERMISSION" , "status" : "APPROVED" , "requestedPermissionId" : "550e8400-e29b-41d4-a716-446655440000" , "reason" : "I need this permission to create a new company for our team" , "reviewedBy" : "990e8400-e29b-41d4-a716-446655440002" , "reviewedAt" : "2024-01-15T14:30:00.000Z" , "reviewNotes" : "Approved based on team requirements" , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T14:30:00.000Z" , "user" : { "id" : "880e8400-e29b-41d4-a716-446655440001" , "email" : "[email protected] " , "fullName" : "John Doe" , "avatar" : "https://example.com/avatars/johndoe.png" }, "requestedPermission" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "COMPANY:CREATE" , "description" : "Allows creating new companies" , "scope" : "GLOBAL" }, "reviewer" : { "id" : "990e8400-e29b-41d4-a716-446655440002" , "email" : "[email protected] " , "fullName" : "Admin User" } } }
Error Responses User does not have permission to view this request
Permission request not found
Update Permission Request curl -X PATCH https://api.example.com/api/permission-requests/{id} \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "reason": "Updated reason for needing this permission" }'
Updates a pending permission request. Only the request creator can update their own requests, and only while the status is PENDING.
Endpoint PATCH /api/permission-requests/{id}
Path Parameters The unique identifier of the permission request to update
Request Body Updated justification (max 1000 characters)
Response Indicates if the request was successful
The updated permission request object
Response Example { "success" : true , "data" : { "id" : "770e8400-e29b-41d4-a716-446655440000" , "userId" : "880e8400-e29b-41d4-a716-446655440001" , "type" : "GLOBAL_PERMISSION" , "status" : "PENDING" , "requestedPermissionId" : "550e8400-e29b-41d4-a716-446655440000" , "reason" : "Updated reason for needing this permission" , "reviewedBy" : null , "reviewedAt" : null , "reviewNotes" : null , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T11:00:00.000Z" , "user" : { "id" : "880e8400-e29b-41d4-a716-446655440001" , "email" : "[email protected] " , "fullName" : "John Doe" , "avatar" : "https://example.com/avatars/johndoe.png" }, "requestedPermission" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "COMPANY:CREATE" , "description" : "Allows creating new companies" , "scope" : "GLOBAL" } }, "message" : "Permission request updated successfully" }
Error Responses Request is not in pending status
{ "success" : false , "error" : "Only pending requests can be updated" }
User does not own this request
Cancel Permission Request curl -X POST https://api.example.com/api/permission-requests/{id}/cancel \ -H "Authorization: Bearer YOUR_TOKEN"
Cancels a pending permission request. Only the request creator can cancel their own requests.
Endpoint POST /api/permission-requests/{id}/cancel
Path Parameters The unique identifier of the permission request to cancel
Response Indicates if the request was successful
The cancelled permission request object
Response Example { "success" : true , "data" : { "id" : "770e8400-e29b-41d4-a716-446655440000" , "userId" : "880e8400-e29b-41d4-a716-446655440001" , "type" : "GLOBAL_PERMISSION" , "status" : "CANCELLED" , "requestedPermissionId" : "550e8400-e29b-41d4-a716-446655440000" , "reason" : "I need this permission to create a new company for our team" , "reviewedBy" : null , "reviewedAt" : null , "reviewNotes" : null , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T11:30:00.000Z" , "user" : { "id" : "880e8400-e29b-41d4-a716-446655440001" , "email" : "[email protected] " , "fullName" : "John Doe" , "avatar" : "https://example.com/avatars/johndoe.png" }, "requestedPermission" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "COMPANY:CREATE" , "description" : "Allows creating new companies" , "scope" : "GLOBAL" } }, "message" : "Permission request cancelled" }
Error Responses Request is not in pending status
{ "success" : false , "error" : "Only pending requests can be cancelled" }
Review Permission Request (Admin) curl -X POST https://api.example.com/api/permission-requests/admin/{id}/review \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "action": "approve", "reviewNotes": "Approved based on team requirements" }'
Approves or rejects a permission request. Requires platform admin privileges. When approved, the permission is automatically granted to the user.
Endpoint POST /api/permission-requests/admin/{id}/review
Path Parameters The unique identifier of the permission request to review
Request Body Review action: approve or reject
Notes about the review decision (max 1000 characters)
Response Indicates if the request was successful
The reviewed permission request object
Success message indicating approval or rejection
Response Example (Approved) { "success" : true , "data" : { "id" : "770e8400-e29b-41d4-a716-446655440000" , "userId" : "880e8400-e29b-41d4-a716-446655440001" , "type" : "GLOBAL_PERMISSION" , "status" : "APPROVED" , "requestedPermissionId" : "550e8400-e29b-41d4-a716-446655440000" , "reason" : "I need this permission to create a new company for our team" , "reviewedBy" : "990e8400-e29b-41d4-a716-446655440002" , "reviewedAt" : "2024-01-15T14:30:00.000Z" , "reviewNotes" : "Approved based on team requirements" , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T14:30:00.000Z" , "user" : { "id" : "880e8400-e29b-41d4-a716-446655440001" , "email" : "[email protected] " , "fullName" : "John Doe" , "avatar" : "https://example.com/avatars/johndoe.png" }, "requestedPermission" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "COMPANY:CREATE" , "description" : "Allows creating new companies" , "scope" : "GLOBAL" }, "reviewer" : { "id" : "990e8400-e29b-41d4-a716-446655440002" , "email" : "[email protected] " , "fullName" : "Admin User" } }, "message" : "Permission request approved and permission granted to user." }
Response Example (Rejected) { "success" : true , "data" : { "id" : "770e8400-e29b-41d4-a716-446655440000" , "userId" : "880e8400-e29b-41d4-a716-446655440001" , "type" : "GLOBAL_PERMISSION" , "status" : "REJECTED" , "requestedPermissionId" : "550e8400-e29b-41d4-a716-446655440000" , "reason" : "I need this permission to create a new company for our team" , "reviewedBy" : "990e8400-e29b-41d4-a716-446655440002" , "reviewedAt" : "2024-01-15T14:30:00.000Z" , "reviewNotes" : "Insufficient justification provided" , "createdAt" : "2024-01-15T10:30:00.000Z" , "updatedAt" : "2024-01-15T14:30:00.000Z" , "user" : { "id" : "880e8400-e29b-41d4-a716-446655440001" , "email" : "[email protected] " , "fullName" : "John Doe" , "avatar" : "https://example.com/avatars/johndoe.png" }, "requestedPermission" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "key" : "COMPANY:CREATE" , "description" : "Allows creating new companies" , "scope" : "GLOBAL" }, "reviewer" : { "id" : "990e8400-e29b-41d4-a716-446655440002" , "email" : "[email protected] " , "fullName" : "Admin User" } }, "message" : "Permission request rejected." }
Error Responses Request is not in pending status
{ "success" : false , "error" : "Only pending requests can be reviewed" }
Permission request not found
Permission Request Statuses Request has been submitted and is awaiting admin review
Request has been approved by an admin. The permission is automatically granted to the user.
Request has been rejected by an admin
Request has been cancelled by the user before review
Permission Request Types Request for a specific global permission. Requires requestedPermissionId.
Custom permission request type for special cases
