🏢 Organization Settings APIs
Self-service organization configuration and management
Executive Summary
Admin Organization Settings APIs provide self-service configuration for organization administrators. Unlike SuperAdmin APIs that manage multiple organizations, these endpoints are scoped to the Admin's own organization only.
✅ Self-Service
Admins manage own org settings
Admins manage own org settings
✅ Plan-Aware
Settings validated against subscription limits
Settings validated against subscription limits
⚠️ Read-Only Plans
Cannot upgrade/downgrade without SuperAdmin
Cannot upgrade/downgrade without SuperAdmin
🎯 Scoped Access
JWT orgId claim enforced
JWT orgId claim enforced
📊 API Inventory
| Controller | Route | Endpoints | Admin Access | Notes |
|---|---|---|---|---|
| AdminOrganizationController | /api/adminorganization | 12 | Own Org Only | Read own org, limited update |
| OrganizationSettingsController | /api/organizationsettings | 6 | Full CRUD | Key-value settings store |
⚙️ Organization Settings
Settings Management
GET
/api/adminorganization/{id}
Get organization details. Admin can only access their own organization.
Own Org Only Existing
PUT
/api/adminorganization/{id}
Update organization name, description, branding. Cannot change plan or status.
Own Org Only Existing
GET
/api/organizationsettings
Get all organization-specific settings (key-value pairs).
Own Org Full Existing
POST
/api/organizationsettings
Create or update a setting. Validated against plan feature flags.
Own Org Full Existing
Available Settings
| Setting Key | Type | Description | Plan Limit |
|---|---|---|---|
max_users | Integer | Maximum users allowed | Defined by plan |
max_devices | Integer | Maximum devices per user | Defined by plan |
session_retention_days | Integer | How long to keep session history | 30-365 days by plan |
enable_exports | Boolean | Allow data exports | Pro+ plans only |
enable_analytics | Boolean | Advanced analytics features | Pro+ plans only |
enable_api_access | Boolean | Organization API key access | Enterprise only |
branding_logo_url | String | Custom logo URL | Enterprise only |
sso_provider | String | SAML/OIDC provider config | Enterprise only |
📊 Plan Limits & Enforcement
Plan Limits Enforcement Flow
═══════════════════════════════════════════════════════════════════════════════
Admin Request: POST /api/organizationsettings
Body: { "key": "max_users", "value": "150" }
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ OrganizationSettingsController │
│ │
│ 1. Extract OrganizationId from JWT claims │
│ 2. Validate setting key is allowed │
│ 3. Check plan limits │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ IPlanFeatureService.ValidateLimit() │ │
│ │ │ │
│ │ Current Plan: "Professional" ($99/mo) │ │
│ │ Plan Features: { maxUsers: 100, enableExports: true } │ │
│ │ │ │
│ │ Requested: max_users = 150 │ │
│ │ Allowed: max_users <= 100 │ │
│ │ │ │
│ │ Result: ❌ VALIDATION FAILED │ │
│ │ Return 400 Bad Request │ │
│ │ "Value exceeds plan limit (100)" │ │
│ │ │ │
│ │ ───────────────────────────────────────────────────────── │ │
│ │ Requested: max_users = 50 │ │
│ │ Allowed: max_users <= 100 ✓ │ │
│ │ │ │
│ │ Result: ✅ VALIDATION PASSED │ │
│ │ Continue to save... │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
Save to DB
│
▼
Return 200 OK
🔄 Settings Change Workflow
Organization Settings Change Flow
═══════════════════════════════════════════════════════════════════════════════
┌──────────┐ ┌──────────────┐ ┌─────────────────┐ ┌─────────────┐
│ Admin │────►│ Angular │────►│ Settings API │────►│ Plan │
│ User │ │ Settings │ │ (Validation) │ │ Service │
└──────────┘ │ Component │ └────────┬────────┘ └─────────────┘
└──────────────┘ │
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌──────────┐
│ ❌ Rej │ │ ⚠️ Warn │ │ ✅ Save │
│ ected │ │ Limit │ │ Setting │
│ (400) │ │ Close │ │ (200) │
└─────────┘ └────┬────┘ └────┬─────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Show upgrade │ │ Refresh cache│
│ prompt │ │ Notify users │
└──────────────┘ └──────────────┘
Frontend Integration:
• Settings form dynamically shows/hides fields based on plan features
• "Upgrade required" badges on premium settings
• Real-time validation before submission
🗄️ Database Dependencies
| Table | Purpose | Key Columns | Indexes |
|---|---|---|---|
| Organizations | Org metadata | Id, Name, PlanId, Status | PK Id |
| OrganizationSettings | Key-value store | OrgId, Key, Value, ModifiedAt | PK (OrgId, Key) |
| Plans | Subscription tiers | Id, Name, Features (JSON), Limits (JSON) | PK Id |
| Subscriptions | Active subscriptions | Id, OrgId, PlanId, Status | IX OrgId (unique) |
⚠️ Security Considerations
JWT OrgId Enforcement
Admin can only modify settings for organization in their JWT claims.
Plan Validation
Cannot bypass plan limits by directly calling API. Server-side validation enforced.
No Approval Workflow
Settings changes apply immediately. No review/approval process for sensitive changes.