RBAC API Documentation (Phase 4)

[kevalyq]

🎯 Objective

Create comprehensive API documentation for RBAC Phase 4 endpoints: Role Management, Permission Management, Direct Permission Assignment, and Temporal Roles (#108).

📋 Scope

Documentation Files to Create

1. docs/api/rbac-endpoints.md

   • Complete API reference for all RBAC endpoints
   • Request/response examples
   • Error codes and meanings
   • Authorization requirements

2. docs/guides/role-management.md

   • How to create roles
   • How to assign permissions to roles
   • How to assign roles to users
   • When to use temporal roles
   • Best practices

3. docs/guides/permission-system.md

   • Permission naming convention
   • Permission organization by resource
   • How to create custom permissions
   • Permission lifecycle (create → assign → revoke)

4. docs/guides/direct-permissions.md

   • When to use direct permissions vs roles
   • How to assign direct permissions
   • Temporal direct permissions
   • Permission inheritance (role + direct)
   • Best practices and use cases

5. docs/guides/temporal-roles.md

   • Vacation coverage scenario
   • Project-based access scenario
   • Temporary elevation scenario
   • How to extend/revoke temporal roles
   • Expiration handling

6. Update README.md

   • Add RBAC overview section
   • Link to detailed docs
   • Quick start examples

7. Update CHANGELOG.md

   • Document v0.2.0 changes
   • List all new endpoints
   • Breaking changes (if any)
   • Migration guide (if needed)

🏗️ Implementation Checklist

API Reference (docs/api/rbac-endpoints.md)

• Role Management Endpoints (5 routes)

  • GET /api/v1/roles - List all roles
  • POST /api/v1/roles - Create role
  • GET /api/v1/roles/{id} - Get role details
  • PATCH /api/v1/roles/{id} - Update role
  • DELETE /api/v1/roles/{id} - Delete role

• Permission Management Endpoints (5 routes)

  • GET /api/v1/permissions - List all permissions
  • POST /api/v1/permissions - Create permission
  • GET /api/v1/permissions/{id} - Get permission details
  • PATCH /api/v1/permissions/{id} - Update permission
  • DELETE /api/v1/permissions/{id} - Delete permission

• Direct Permission Endpoints (4 routes)

  • GET /api/v1/users/{id}/permissions - List all permissions
  • POST /api/v1/users/{id}/permissions - Assign direct permission
  • DELETE /api/v1/users/{id}/permissions/{permission} - Revoke
  • GET /api/v1/users/{id}/permissions/direct - List direct only

• Temporal Role Endpoints (existing, document)

  • POST /api/v1/users/{id}/roles - Assign role (temporal support)
  • DELETE /api/v1/users/{id}/roles/{role} - Revoke role

• For each endpoint:

  • HTTP method + path
  • Authorization requirements
  • Request body schema (JSON)
  • Response body schema (JSON)
  • Success status codes
  • Error status codes (401, 403, 422, 404)
  • cURL examples
  • JavaScript fetch examples

Guides

• Role Management Guide (docs/guides/role-management.md)

  • Create role step-by-step
  • Assign permissions to role
  • Assign role to user
  • Remove role from user
  • Delete role (with safety check)
  • Predefined roles overview

• Permission System Guide (docs/guides/permission-system.md)

  • Naming convention: resource.action
  • List of all resources
  • Common actions vs special actions
  • Permission matrix for predefined roles
  • How to add custom permissions

• Direct Permissions Guide (docs/guides/direct-permissions.md)

  • Use cases (when to use direct vs roles)
  • Assign direct permission
  • Temporal direct permissions
  • Permission inheritance diagram
  • Best practices

• Temporal Roles Guide (docs/guides/temporal-roles.md)

  • 4 use case scenarios (from 🔐 Implement RBAC System (Role-Based Access Control) #5)
  • API examples for each scenario
  • Expiration handling
  • Extend expiration
  • Revoke before expiration

README Update

• Add "RBAC System" section
• Quick overview (3-5 sentences)
• Link to detailed docs
• Quick start code example
• Link to API reference

CHANGELOG Update

• Add v0.2.0 section
• List all new features
• List all new endpoints
• Document breaking changes (if any)
• Migration notes (if needed)

Quality Gates

• Markdownlint passes
• All links work (no 404s)
• Code examples tested
• REUSE compliance (license headers)
• Consistent formatting

✅ Acceptance Criteria

• All 7 documentation files created/updated
• 14+ API endpoints fully documented
• Request/response examples for all endpoints
• Error codes explained
• 4+ use case guides written
• README updated with RBAC section
• CHANGELOG updated with v0.2.0
• Markdownlint clean
• All links work

📊 Documentation Structure

docs/
├── api/
│   └── rbac-endpoints.md          # Complete API reference (NEW)
├── guides/
│   ├── role-management.md         # How-to guide (NEW)
│   ├── permission-system.md       # Permission naming & organization (NEW)
│   ├── direct-permissions.md      # Direct permission usage (NEW)
│   └── temporal-roles.md          # Temporal roles patterns (NEW)
README.md                          # Add RBAC section (UPDATE)
CHANGELOG.md                       # Add v0.2.0 changes (UPDATE)

🔗 Related Issues

Part of: #108 - RBAC Phase 4
Depends on:

• PR [DRAFT] feat: RBAC Phase 4 - Role Management CRUD API #131 (Role Management API)
• Permission Management API (sub-issue)
• Direct Permission API (sub-issue)
• Seeder (sub-issue)

References:

• 🔐 Implement RBAC System (Role-Based Access Control) #5 - Original RBAC requirements (4 use cases)
• [EPIC] Migrate Permission System from 'web' to 'sanctum' Guard #125 - Guard architecture (reference for auth docs)

⏱️ Effort Estimate

Time: 4-5 hours
Breakdown:

• API reference: 2h
• How-to guides: 2h
• README/CHANGELOG: 0.5h
• Review/links check: 0.5h

Complexity: Low (documentation, no code)

🎯 Documentation Style Guide

Code Examples

• Use cURL for shell examples
• Use JavaScript fetch for frontend examples
• Include full request/response bodies
• Show success AND error responses

Structure

• Start with "What" (brief description)
• Then "Why" (use cases)
• Then "How" (step-by-step examples)
• End with "Gotchas" (common mistakes)

Tone

• Clear and concise
• Assume reader is developer
• Explain "why" for architectural decisions
• Link to related docs

📝 Example Snippets

API Endpoint Documentation:

### Create Role

Creates a new role with assigned permissions.

**Endpoint:** `POST /api/v1/roles`

**Authorization:** Requires `roles.create` permission

**Request Body:**
```json
{
  "name": "Regional Manager",
  "description": "Manages multiple branches",
  "permissions": ["employees.read", "shifts.read"]
}

Success Response (201 Created):

{
  "data": {
    "id": 5,
    "name": "Regional Manager",
    "permissions": ["employees.read", "shifts.read"],
    "created_at": "2025-11-09T10:00:00Z"
  }
}

Error Response (422 Unprocessable):

{
  "message": "The name has already been taken.",
  "errors": {
    "name": ["A role with this name already exists."]
  }
}

## 📝 Review Checklist

Before creating PR:
- [ ] All endpoints documented
- [ ] Request/response schemas complete
- [ ] cURL examples tested
- [ ] Use case guides cover 4 scenarios from #5
- [ ] Links between docs work
- [ ] Markdownlint passes
- [ ] REUSE compliance

---

**Created:** 2025-11-09  
**Category:** Documentation  
**Size:** ~1000-1500 lines total (across all files)  
**Risk:** Low (documentation only, no code changes)

[github-actions]

✅ This issue has been added to the SecPal Feature Roadmap with status: 💡 Ideas

New idea - needs discussion and evaluation

Status Flow:
💡 Ideas → 💬 Discussion → 📥 Backlog → 📋 Planned → 🚧 In Progress → 👀 In Review → ✅ Done

Note: Ideas that won't be implemented should be moved to 🚫 Won't Do with a reason.

[kevalyq]

🔧 Update: contracts Repository Integration

Key Changes:

1. OpenAPI Specs as Single Source of Truth

This issue should update the contracts repository (docs/openapi.yaml) instead of creating separate Markdown API reference files.

contracts Repository Structure:

• Base URL: https://api.secpal.app/v1
• Spec file: contracts/docs/openapi.yaml
• OpenAPI version: 3.1.0

2. Revised Documentation Deliverables

Update contracts Repository:

• contracts/docs/openapi.yaml - Add RBAC endpoints (14 new routes)
  • Role Management: 5 endpoints
  • Permission Management: 5 endpoints
  • Direct Permission Assignment: 4 endpoints
  • Update existing temporal role assignment endpoints

Create in api Repository:

• docs/guides/role-management.md - How-to guide
• docs/guides/permission-system.md - Permission naming & organization
• docs/guides/direct-permissions.md - Direct permission usage
• docs/guides/temporal-roles.md - Temporal roles patterns
• Update README.md with RBAC section
• Update CHANGELOG.md with v0.2.0 changes

3. Updated Workflow

Step 1: Update OpenAPI Specs (contracts repo)

# contracts/docs/openapi.yaml
paths:
  /v1/roles:
    get:
      summary: List all roles
      operationId: listRoles
      security:
        - bearerAuth: []
      # ... (full OpenAPI spec)

Step 2: Generate API Documentation

cd contracts
npm run docs:build  # Generates HTML/Redoc from openapi.yaml

Step 3: Write How-To Guides (api repo)

• Focus on use cases, not API reference
• Link to contracts repo for full API specs

4. Correct API Paths

✅ Correct: /v1/roles (domain is already api.secpal.app)
❌ Wrong: /api/v1/roles (redundant /api/ prefix)

Full URLs:

• Production: https://api.secpal.app/v1/roles
• Customer: https://api.customer-domain.com/v1/roles

---

Impact on This Issue:

• Add task: Update contracts/docs/openapi.yaml
• Remove task: Create docs/api/rbac-endpoints.md (covered by OpenAPI)
• Guides remain in api repo (how-to, not API reference)

This ensures single source of truth for API contracts! 🚀