Role Repository

List all role definitions

{
  "data": [
    {
      "role_id": "role_coord_001",
      "role_name": "coordinator",
      "display_name": "Program Coordinator",
      "description": "Manages program activities and participants",
      "is_system_role": true,
      "cache_ttl_seconds": 300,
      "created_at": "2026-01-10T00:00:00Z",
      "updated_at": "2026-03-01T00:00:00Z"
    },
    {
      "role_id": "role_mentor_002",
      "role_name": "mentor",
      "display_name": "Mentor",
      "description": "Guides and supports program participants",
      "is_system_role": true,
      "cache_ttl_seconds": 300,
      "created_at": "2026-01-10T00:00:00Z",
      "updated_at": "2026-03-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

Get a role definition by ID

{
  "role_id": "role_coord_001",
  "role_name": "coordinator",
  "display_name": "Program Coordinator",
  "description": "Manages program activities and participants",
  "is_system_role": true,
  "cache_ttl_seconds": 300,
  "created_at": "2026-01-10T00:00:00Z",
  "updated_at": "2026-03-01T00:00:00Z"
}

Create a new role definition

{
  "role_name": "supervisor",
  "display_name": "Program Supervisor",
  "description": "Oversees multiple coordinators and their programs",
  "is_system_role": false,
  "cache_ttl_seconds": 600
}

{
  "role_id": "role_super_006",
  "role_name": "supervisor",
  "display_name": "Program Supervisor",
  "description": "Oversees multiple coordinators and their programs",
  "is_system_role": false,
  "cache_ttl_seconds": 600,
  "created_at": "2026-03-26T10:20:00Z",
  "updated_at": "2026-03-26T10:20:00Z"
}

Update a role definition

{
  "display_name": "Senior Program Supervisor",
  "description": "Senior oversight of multiple program coordinators",
  "cache_ttl_seconds": 900
}

{
  "role_id": "role_super_006",
  "role_name": "supervisor",
  "display_name": "Senior Program Supervisor",
  "description": "Senior oversight of multiple program coordinators",
  "is_system_role": false,
  "cache_ttl_seconds": 900,
  "created_at": "2026-03-26T10:20:00Z",
  "updated_at": "2026-03-26T10:30:00Z"
}

Delete a role definition and invalidate its cache

{
  "deleted": true,
  "role_id": "role_super_006",
  "cache_invalidated": true
}

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}