Skip to main content

WF-107: Organization Settings Management

Overview​

This workflow handles organization-level configuration changes including company branding, billing information, security policies, API key management, and subscription settings. Only organization owners and admins can modify these settings.

Trigger: HTTP PUT/PATCH to /api/v1/organizations/{org_id}/settings Duration: ~1-3 seconds Related Workflows: WF-002 (Subscription), WF-024 (Payment Method)

Prerequisites​

Before modifying organization settings:

  • User must be organization owner or admin
  • Organization must be in active status
  • Valid authentication token

Workflow Diagram​

Step-by-Step Narrative​

Step 1: Authentication & Authorization​

  • Node: Validate Request
  • Type: Auth Middleware
  • Actions:
    • Validates JWT token from Authorization header
    • Extracts user_id and tenant_id from token
    • Verifies user has owner or admin role in organization
    • Rejects with 403 if insufficient permissions

Step 2: Validate Settings Payload​

  • Node: Schema Validation
  • Type: Request Validation
  • Actions:
    • Validates request body against organization settings schema
    • Checks field constraints:
      • name: 2-100 characters, alphanumeric with spaces
      • billing_email: Valid email format
      • logo_url: Valid HTTPS URL or null
      • primary_color: Valid hex color code
      • session_timeout_minutes: 15-480 range
      • require_2fa: Boolean

Step 3: Process Setting Categories​

3a: General Settings​

  • Fields: name, display_name, timezone, language
  • Actions:
    • Updates organization profile
    • Validates timezone against IANA database
    • Propagates name change to related records

3b: Branding Settings​

  • Fields: logo_url, primary_color, secondary_color, favicon_url
  • Actions:
    • Validates image URLs are accessible
    • Stores branding configuration
    • Triggers CDN cache invalidation if needed

3c: Billing Settings​

  • Fields: billing_email, billing_address, tax_id, invoice_prefix
  • Actions:
    • Updates Stripe customer metadata
    • Sends notification to old and new billing email
    • Validates tax ID format by country

3d: Security Settings​

  • Fields: require_2fa, session_timeout_minutes, allowed_ip_ranges, sso_enabled
  • Actions:
    • If enabling require_2fa, queues notification to users without 2FA
    • Validates IP ranges in CIDR format
    • Updates session policies for all active sessions

3e: API Key Management​

  • Fields: api_keys (array of key operations)
  • Actions:
    • Create: Generates new API key with specified scopes
    • Revoke: Invalidates existing key immediately
    • Rotate: Creates new key, schedules old key expiration (24h grace)
    • All operations logged to audit trail

Step 4: Audit Logging​

  • Node: Audit Trail
  • Type: PostgreSQL Insert
  • Table: audit_logs
  • Actions:
    • Records all setting changes with before/after values
    • Captures user_id, ip_address, user_agent
    • Sets action type to organization.settings.updated
    • Stores changed fields in JSON details column

Step 5: Return Response​

  • Node: Response
  • Type: HTTP Response
  • Actions:
    • Returns updated organization settings object
    • Excludes sensitive fields (API key secrets)
    • Includes updated_at timestamp
    • Returns 200 OK on success

Error Handling​

ErrorCodeResolution
Unauthorized401Provide valid JWT token
Forbidden403Requires owner/admin role
Validation Error400Check field constraints
Org Not Found404Verify organization ID
Conflict409Name already taken

API Endpoints​

MethodEndpointDescription
GET/api/v1/organizations/{id}/settingsGet current settings
PUT/api/v1/organizations/{id}/settingsReplace all settings
PATCH/api/v1/organizations/{id}/settingsPartial update
POST/api/v1/organizations/{id}/api-keysCreate API key
DELETE/api/v1/organizations/{id}/api-keys/{key_id}Revoke API key