Roles & Permissions API

Organization API

The Roles API provides role-based access control (RBAC) and permission management.

Quick Navigation

• Overview
• Base Path
• Authentication
• Roles Flow
• Endpoints
• Internal Notes
• Swagger Documentation

Overview

This module provides:

• Role creation and management
• Permission management
• Role templates
• Access requests and approvals
• Temporary access grants
• Access reviews

Base Path

All roles endpoints are prefixed with /api/v1/roles

Authentication

All endpoints require authentication:

Authorization: Bearer <access_token>

Roles Flow

The Roles & Permissions API provides comprehensive role-based access control. Administrators can create roles, manage permissions, use role templates, handle access requests, and grant temporary access. The system supports access reviews for compliance and security.

Roles Flow Diagram

View Flow Diagram

Roles Flow Overview:

This flow diagram illustrates the role-based access control (RBAC) workflow. It shows how roles are created and managed, how permissions are assigned, how access requests are handled, and how temporary access is granted.

Key Flow Components:

1. Role Management: Create, update, and delete roles with associated permissions
2. Permission Management: Define and manage granular permissions for resources
3. Role Templates: Use predefined role templates for common access patterns
4. Access Requests: Users can request access, which administrators can approve
5. Temporary Access: Grant time-limited access for specific use cases
6. Access Reviews: Periodic reviews of user access for compliance and security
7. Effective Permissions: Calculate effective permissions considering all role assignments

Internal Developer Notes:

• Roles can be organization-scoped or system-wide
• Permissions are hierarchical and can be inherited
• Access requests enable self-service access management
• Temporary access provides time-bound access for contractors or temporary projects
• Access reviews support compliance requirements

Endpoints

Method	Endpoint	Description
POST	/	Create role
GET	/	List roles
GET	/{role_id}	Get role details
PUT	/{role_id}	Update role
DELETE	/{role_id}	Delete role
GET	/permissions	List permissions
POST	/templates	Create role template
GET	/templates	List role templates
POST	/access-requests	Create access request
GET	/access-requests	List access requests
POST	/access-requests/{request_id}/approve	Approve access request
GET	/users/{user_id}/effective-permissions	Get effective permissions
POST	/temporary-access	Grant temporary access
GET	/access-reviews	List access reviews
GET	/me/permissions	Get own permissions

Internal Notes

• [WARNING] Not implemented - All endpoints have TODO comments
• Endpoint stubs exist with proper schemas
• Implementation needed for full RBAC functionality

Swagger Documentation

Interactive API documentation available at: /docs#/roles