Use Case 013: Application Registration and Management

Overview

Property Value
Use Case ID UC-013
Use Case Name Application Registration and Management
Module Application Registry - Application Lifecycle
Priority High
Status Implemented
Version 1.0
Last Updated January 30, 2026

Description

This use case describes the comprehensive lifecycle management of Riptide applications within the Application Manager platform. It covers the complete process of registering new applications (such as Fee Manager, Value Manager, Workflow Designer), configuring their properties, managing their operational status, monitoring their health and performance, tracking versioning, and eventually decommissioning them. The system provides centralized control over the application ecosystem, enabling administrators to manage application access, credentials, health monitoring, and usage analytics.

Actors

Actor Description Role
Platform Administrator System administrator managing the application registry Primary
Application Riptide application instance (Fee Manager, Value Manager, etc.) Supporting
System Application Manager platform Supporting
DevOps Engineer Engineer deploying and monitoring applications Secondary
Application Owner Business owner responsible for specific application Secondary
Monitoring Service Health check and metrics collection system Supporting

Preconditions

  1. Application Manager is running with administrative access enabled
  2. Database schema includes application registry tables
  3. Administrator has valid authentication and authorization
  4. Network connectivity exists between Application Manager and applications
  5. Health check endpoints are standardized across applications
  6. API key generation service is operational
  7. Monitoring service is configured and running

Postconditions

Success Postconditions

  1. Application record created or updated in registry
  2. Application credentials (API keys) generated and stored securely
  3. Health check monitoring activated for the application
  4. Application access permissions configured
  5. Application version tracked and recorded
  6. Usage statistics collection initiated
  7. Activity logged in audit trail
  8. Dependent applications notified of changes (if applicable)

Failure Postconditions

  1. No application record created if validation fails
  2. Error message logged and returned to administrator
  3. Partial data rolled back if transaction fails
  4. Existing application state remains unchanged on update failure

Triggers

  • Administrator navigates to application management interface
  • Administrator initiates new application registration
  • Application health check fails triggering alert
  • Application version update detected
  • Scheduled audit of registered applications
  • API call to application management endpoint
  • Application decommission request submitted

Basic Flow (Happy Path)

sequenceDiagram actor Admin as Platform Administrator participant UI as Admin UI participant API as Application Manager API participant DB as Registry Database participant App as Riptide Application participant Monitor as Monitoring Service participant Audit as Audit Log Admin->>UI: Navigate to Applications Registry UI->>API: GET /api/v1/applications API->>DB: Query all registered applications DB->>API: Return application list API->>UI: Display applications with status UI->>Admin: Show applications dashboard Admin->>UI: Click "Register New Application" UI->>Admin: Display registration form Admin->>UI: Submit application details Note over Admin,UI: Name, Description, URL, Icon,<br/>Trial-Enabled, Version, etc. UI->>API: POST /api/v1/applications API->>API: Validate input data API->>DB: Check application name uniqueness DB->>API: Name is unique API->>API: Generate API credentials Note over API: Create API Key and Secret API->>DB: Create application record DB->>API: Application created (ID returned) API->>DB: Store API credentials (encrypted) DB->>API: Credentials stored API->>Monitor: Register health check endpoint Monitor->>App: Perform initial health check App->>Monitor: Return health status Monitor->>API: Health check registered API->>Audit: Log application registration Audit->>API: Event logged API->>UI: 201 Created (application details) UI->>Admin: Show success with API credentials Note over Admin,UI: Admin securely shares credentials<br/>with application team App->>API: Validate API key on first call API->>DB: Verify API credentials DB->>API: Credentials valid API->>App: Authentication confirmed Monitor->>App: Periodic health checks (every 60s) App->>Monitor: Return health status Monitor->>DB: Update application health status

Detailed Steps

  1. Administrator Accesses Application Registry

    • Administrator logs into Application Manager with admin privileges
    • Navigates to /admin/applications or equivalent endpoint
    • System displays list of registered applications with key metrics

  2. Administrator Initiates New Registration

    • Clicks "Register New Application" button
    • System displays comprehensive registration form
    • Form includes all required and optional fields

  3. Administrator Provides Application Information

    • Application Name (required, unique, 2-100 characters)
    • Display Name (required, user-friendly name)
    • Description (required, 10-500 characters)
    • Base URL (required, valid HTTPS URL)
    • Icon URL (optional, icon for UI display)
    • Trial Enabled (boolean, default: false)
    • Premium Only (boolean, default: false)
    • Version (required, semantic versioning format)
    • Health Check Endpoint (required, relative path)
    • Documentation URL (optional)
    • Support Email (optional)
    • Application Category (dropdown: Workflow, Finance, Analytics, etc.)
    • Dependencies (multi-select: other applications this depends on)

  4. System Validates Application Data

    • Verify all required fields are present
    • Validate URL formats (must be HTTPS for production)
    • Check application name is unique (case-insensitive)
    • Validate version format (e.g., 1.2.3, 2.0.0-beta)
    • Verify health check endpoint returns 200 OK
    • Check for circular dependencies if dependencies specified
    • Validate icon URL is accessible (if provided)

  5. System Generates API Credentials

    • Generate unique Application ID (GUID)
    • Generate API Key (32-character alphanumeric, prefix: RIPTIDE_)
    • Generate API Secret (64-character alphanumeric)
    • Create key hash for secure storage (using bcrypt or similar)
    • Generate webhook secret (if webhooks supported)
    • Set credentials expiration policy (e.g., rotate every 365 days)

  6. System Creates Application Record

    • Insert application record into Applications table
    • Set IsActive = true
    • Set IsTrialEnabled based on input
    • Set IsPremiumOnly based on input
    • Store creation timestamp and creating administrator ID
    • Initialize usage counters to zero
    • Set health status to "Unknown" initially

  7. System Stores API Credentials

    • Insert credentials into ApplicationCredentials table
    • Store API key in plain text (for display once)
    • Store API secret hash (never store plain secret after initial display)
    • Link credentials to application ID
    • Set IsActive = true for credentials
    • Record creation timestamp

  8. System Registers Health Monitoring

    • Configure health check endpoint: {BaseURL}{HealthCheckEndpoint}
    • Set check interval (default: 60 seconds)
    • Set timeout (default: 10 seconds)
    • Set failure threshold (default: 3 consecutive failures)
    • Perform initial health check
    • Store initial health status in database
    • Schedule periodic health checks

  9. System Configures Default Access

    • Create default access rules (if defined)
    • Link application to default user roles (e.g., all premium users)
    • Configure trial access rules if trial-enabled
    • Set up usage quota defaults

  10. System Returns Success Response

    • Return 201 Created status
    • Include complete application details
    • Critically: Display API credentials ONE TIME ONLY
    • Provide instructions for credential storage
    • Show next steps for application integration

  11. Administrator Records Credentials

    • Administrator copies API key and secret
    • Administrator securely shares with application development team
    • Application team configures credentials in application settings

  12. Application Integrates with Platform

    • Application configured with API credentials
    • Application makes first validation call to Application Manager
    • Application Manager validates credentials
    • Application begins health check responses
    • Application available for user access

Alternative Flows

Alt Flow 1: Application Name Already Exists

sequenceDiagram actor Admin as Platform Administrator participant API as Application Manager API participant DB as Registry Database Admin->>API: POST /api/v1/applications (duplicate name) API->>DB: Check if application name exists DB->>API: Name found in database API->>API: Check application status alt Application Active API->>Admin: 409 Conflict - Application name already in use Note over Admin,API: Suggest different name or<br/>update existing application else Application Archived API->>Admin: 409 Conflict - Name used by archived app Note over Admin,API: Suggest restore or use<br/>different name end

Steps:

  1. System detects duplicate name during validation (step 4)
  2. System checks status of existing application with same name
  3. If existing application is active:
    • Return 409 Conflict with message: "Application name already exists. Please choose a different name."
    • Suggest viewing or editing the existing application
  4. If existing application is archived:
    • Return 409 Conflict with message: "This name was used by an archived application. Either restore that application or choose a different name."
    • Provide link to archived application details

Alt Flow 2: Health Check Endpoint Not Accessible

sequenceDiagram actor Admin as Platform Administrator participant API as Application Manager API participant Monitor as Monitoring Service participant App as Riptide Application Admin->>API: POST /api/v1/applications API->>Monitor: Register health check endpoint Monitor->>App: Perform initial health check App--xMonitor: Connection timeout / 404 / 500 Monitor->>API: Health check failed alt Strict Validation Mode API->>Admin: 400 Bad Request - Health check failed Note over Admin,API: Registration blocked until<br/>health check succeeds else Permissive Mode API->>API: Create application with warning API->>Admin: 201 Created (with health warning) Note over Admin,API: Application registered but<br/>health monitoring needs attention end

Steps:

  1. Initial health check fails during step 8
  2. System determines validation mode (strict or permissive)
  3. If strict mode enabled:
    • Registration fails with 400 Bad Request
    • Error message: "Health check endpoint not accessible. Verify the URL and endpoint path."
    • Provide diagnostic information (timeout, status code, error message)
    • Administrator must fix health check before retrying
  4. If permissive mode enabled:
    • Registration succeeds with warning
    • Application marked with HealthStatus = "Unhealthy"
    • Administrator notified to investigate health check issue
    • Monitoring service continues retry attempts

Alt Flow 3: Updating Application Configuration

flowchart TD A[Admin selects application] --> B{What to update?} B -->|Basic info| C[Update name, description, URLs] B -->|Status| D[Enable/Disable application] B -->|Trial settings| E[Toggle trial-enabled flag] B -->|Version| F[Update version number] B -->|Credentials| G[Rotate API credentials] B -->|Dependencies| H[Update dependency list] C --> I[Validate changes] D --> I E --> I F --> I G --> J[Generate new credentials] H --> K[Check circular dependencies] I --> L{Valid?} J --> L K --> L L -->|Yes| M[Update database] L -->|No| N[Return validation error] M --> O[Log audit event] O --> P[Notify dependent systems] P --> Q[Return success] N --> R[Display errors to admin]

Steps:

  1. Administrator selects application from list
  2. Administrator clicks "Edit" or specific action (Enable/Disable, Rotate Credentials, etc.)
  3. System displays appropriate edit form pre-filled with current values
  4. Administrator makes changes
  5. System validates changes:
    • Name uniqueness (if changed)
    • URL format validation
    • Version format validation
    • Dependency cycle detection
  6. System updates application record
  7. System logs audit event with old and new values
  8. If credentials rotated:
    • Old credentials marked as deprecated (grace period: 24 hours)
    • New credentials generated and displayed
    • Application team notified of credential rotation
  9. If dependencies changed:
    • Validate no circular dependencies
    • Notify dependent applications of change
  10. System returns success response with updated application details

Alt Flow 4: Disabling/Enabling Application

sequenceDiagram actor Admin as Platform Administrator participant API as Application Manager API participant DB as Registry Database participant Users as Active Users participant App as Riptide Application Admin->>API: POST /api/v1/applications/{id}/disable API->>DB: Check current application status DB->>API: Application is active API->>DB: Query active user sessions for this app DB->>API: Return active session count alt Has Active Users API->>Admin: Show confirmation dialog Note over Admin,API: "50 users currently using this app.<br/>Continue?" Admin->>API: Confirm disable action end API->>DB: Update IsActive = false DB->>API: Update successful API->>Users: Notify active users (via session manager) Note over Users: "Application unavailable. Please save work." API->>App: Notify application of disable event App->>API: Acknowledge API->>API: Log audit event API->>Admin: 200 OK - Application disabled Note over Admin,App: Application remains registered but<br/>users cannot access it

Steps:

  1. Administrator selects application and clicks "Disable"
  2. System checks for active user sessions
  3. If active users exist:
    • Display warning: "X users are currently using this application. Disabling will prevent new access."
    • Request confirmation
  4. If administrator confirms:
    • Update IsActive = false
    • Log audit event with reason
    • Send notification to active users via session manager
    • Application remains in registry but access is denied
  5. To re-enable:
    • Administrator clicks "Enable"
    • System sets IsActive = true
    • Access immediately restored
    • Users notified application is available again

Alt Flow 5: Decommissioning/Archiving Application

flowchart TD A[Admin initiates decommission] --> B{Pre-checks} B --> C[Check active users] B --> D[Check dependent applications] B --> E[Check data retention policy] C --> F{Has active users?} F -->|Yes| G[Warn admin, request confirmation] F -->|No| H[Proceed] D --> I{Has dependencies?} I -->|Yes| J[List dependent apps, block decommission] I -->|No| H E --> K{Data to preserve?} K -->|Yes| L[Export usage history & configs] K -->|No| H G --> M{Admin confirms?} M -->|No| N[Cancel decommission] M -->|Yes| H J --> O[Admin must remove dependencies first] L --> H H --> P[Update status to 'Archived'] P --> Q[Revoke all API credentials] Q --> R[Remove from active discovery] R --> S[Preserve audit history] S --> T[Log decommission event] T --> U[Complete]

Steps:

  1. Administrator selects application and clicks "Decommission"
  2. System performs pre-decommission checks:
    • Query active users accessing the application
    • Check if other applications depend on this one
    • Verify data retention requirements
  3. If dependent applications exist:
    • Block decommission
    • Display error: "Cannot decommission. The following applications depend on this: [list]"
    • Administrator must update or remove dependencies first
  4. If active users exist:
    • Display warning with user count
    • Require explicit confirmation
  5. If administrator confirms:
    • Export application configuration and usage history
    • Update Status = 'Archived'
    • Set ArchivedAt timestamp
    • Revoke all API credentials (set IsActive = false)
    • Remove from health check monitoring
    • Remove from user application discovery lists
    • Preserve all audit history (never delete)
  6. Application no longer accessible but can be restored if needed

Alt Flow 6: Rotating API Credentials

sequenceDiagram actor Admin as Platform Administrator participant API as Application Manager API participant DB as Registry Database participant App as Riptide Application participant Team as Application Team Admin->>API: POST /api/v1/applications/{id}/rotate-credentials API->>DB: Query current credentials DB->>API: Return active credentials API->>API: Generate new API key and secret API->>DB: Insert new credentials (active) API->>DB: Mark old credentials as deprecated Note over DB: Old credentials valid for 24h grace period API->>Team: Send notification email Note over Team: "API credentials rotated for [App].<br/>Update within 24 hours." API->>API: Log credential rotation event API->>Admin: 200 OK with new credentials Note over Admin,API: Display new credentials ONE TIME Admin->>Team: Securely share new credentials Team->>App: Update application configuration App->>API: Test new credentials API->>App: Credentials validated Note over API,DB: After 24 hours, auto-revoke old credentials

Steps:

  1. Administrator identifies need for credential rotation (security policy, compromise, scheduled rotation)
  2. Administrator clicks "Rotate Credentials" for application
  3. System generates new API key and secret
  4. System inserts new credentials into database with IsActive = true
  5. System updates old credentials:
    • Set IsDeprecated = true
    • Set DeprecatedAt = now()
    • Set ExpiresAt = now() + 24 hours
  6. System sends notification email to registered application team contacts
  7. System logs credential rotation in audit trail
  8. System displays new credentials ONE TIME ONLY to administrator
  9. Administrator securely shares new credentials with application team
  10. Application team updates application configuration with new credentials
  11. After 24-hour grace period:
    • Background job revokes old credentials (sets IsActive = false)
    • Old credentials no longer accepted
    • If old credentials used, return 401 Unauthorized with message: "API credentials expired. Please use updated credentials."

Business Rules

Rule ID Description Enforcement
BR-001 Application names must be unique (case-insensitive) across all active and archived applications Database unique constraint + API validation
BR-002 Production application URLs must use HTTPS protocol URL validation
BR-003 API keys must be 32 alphanumeric characters prefixed with RIPTIDE_ Key generation logic
BR-004 API secrets must be 64 cryptographically random alphanumeric characters Secret generation logic
BR-005 Application versions must follow semantic versioning (MAJOR.MINOR.PATCH) Regex validation
BR-006 Health check endpoints must respond within 10 seconds Monitoring service timeout
BR-007 Applications with 3 consecutive failed health checks marked as unhealthy Monitoring service logic
BR-008 Applications cannot be deleted, only archived (audit trail preservation) API business logic
BR-009 Applications with active dependencies cannot be archived Pre-archive validation
BR-010 API credential rotation requires 24-hour grace period for old credentials Credential management service
BR-011 Trial-enabled applications must be free tier compatible Configuration validation
BR-012 Application descriptions must be 10-500 characters Data validation
BR-013 Maximum 10 application dependencies allowed per application Dependency validation
BR-014 Circular dependencies are not allowed Dependency graph validation
BR-015 Health check must succeed at least once during registration (strict mode) Registration validation

Data Requirements

Application Record

{
  "Id": "uuid-v4",
  "Name": "string (required, unique, 2-100 chars, alphanumeric + hyphens)",
  "DisplayName": "string (required, 2-100 chars)",
  "Description": "string (required, 10-500 chars)",
  "BaseUrl": "string (required, valid HTTPS URL)",
  "IconUrl": "string (optional, valid URL)",
  "IsActive": "boolean (default: true)",
  "IsTrialEnabled": "boolean (default: false)",
  "IsPremiumOnly": "boolean (default: false)",
  "Version": "string (semantic version format)",
  "HealthCheckEndpoint": "string (required, relative path)",
  "HealthCheckIntervalSeconds": "integer (default: 60)",
  "HealthStatus": "enum (Unknown, Healthy, Degraded, Unhealthy)",
  "LastHealthCheckAt": "datetime (UTC, nullable)",
  "ConsecutiveFailures": "integer (default: 0)",
  "DocumentationUrl": "string (optional, valid URL)",
  "SupportEmail": "string (optional, valid email)",
  "Category": "enum (Workflow, Finance, Analytics, Reporting, Integration, Admin)",
  "Tags": "array of strings (optional)",
  "CreatedAt": "datetime (UTC)",
  "UpdatedAt": "datetime (UTC)",
  "CreatedBy": "string (admin user ID)",
  "ArchivedAt": "datetime (UTC, nullable)",
  "ArchivedBy": "string (admin user ID, nullable)",
  "ArchiveReason": "string (optional)",
  "TotalUsers": "integer (denormalized count, updated periodically)",
  "TotalApiCalls": "bigint (cumulative counter)",
  "LastApiCallAt": "datetime (UTC, nullable)"
}

Application Credentials

{
  "Id": "uuid-v4",
  "ApplicationId": "uuid-v4 (foreign key)",
  "ApiKey": "string (32 chars, prefixed RIPTIDE_, stored plain)",
  "ApiSecretHash": "string (bcrypt hash of secret)",
  "WebhookSecret": "string (optional, 32 chars)",
  "IsActive": "boolean (default: true)",
  "IsDeprecated": "boolean (default: false)",
  "CreatedAt": "datetime (UTC)",
  "DeprecatedAt": "datetime (UTC, nullable)",
  "ExpiresAt": "datetime (UTC, nullable)",
  "LastUsedAt": "datetime (UTC, nullable)",
  "UsageCount": "integer (default: 0)"
}

Application Dependency

{
  "Id": "uuid-v4",
  "ApplicationId": "uuid-v4 (foreign key, dependent app)",
  "DependsOnApplicationId": "uuid-v4 (foreign key, dependency)",
  "DependencyType": "enum (Required, Optional, Integration)",
  "CreatedAt": "datetime (UTC)",
  "Notes": "string (optional, describe why dependency exists)"
}

Application Usage Statistics

{
  "Id": "uuid-v4",
  "ApplicationId": "uuid-v4 (foreign key)",
  "Date": "date (partition key)",
  "ActiveUsers": "integer",
  "NewUsers": "integer",
  "TrialUsers": "integer",
  "PremiumUsers": "integer",
  "TotalApiCalls": "integer",
  "SuccessfulCalls": "integer",
  "FailedCalls": "integer",
  "AverageResponseTimeMs": "integer",
  "PeakConcurrentUsers": "integer",
  "ErrorRate": "decimal (percentage)"
}

Application Access Grant

{
  "Id": "uuid-v4",
  "ApplicationId": "uuid-v4 (foreign key)",
  "UserId": "uuid-v4 (foreign key)",
  "GrantType": "enum (Trial, Premium, Admin, Custom)",
  "GrantedAt": "datetime (UTC)",
  "ExpiresAt": "datetime (UTC, nullable)",
  "GrantedBy": "string (admin user ID, nullable)",
  "IsRevoked": "boolean (default: false)",
  "RevokedAt": "datetime (UTC, nullable)",
  "RevokedBy": "string (admin user ID, nullable)"
}

User Interface

Application Registry Dashboard

┌─────────────────────────────────────────────────────────────────────────┐
│  Application Registry                                    [+ Register New] │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                                           │
│  Filters: [All] [Active] [Inactive] [Archived]  Search: [___________]   │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ 🔧 Fee Manager                                     ✅ Healthy      │  │
│  │ v2.1.5 • Trial Enabled • 1,247 active users                       │  │
│  │ https://fee-manager.riptide.example.com                           │  │
│  │ [View Details] [Edit] [Disable] [Rotate Credentials] [Analytics] │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ 💰 Value Manager                                   ✅ Healthy      │  │
│  │ v3.0.2 • Premium Only • 523 active users                          │  │
│  │ https://value-manager.riptide.example.com                         │  │
│  │ [View Details] [Edit] [Disable] [Rotate Credentials] [Analytics] │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ 🔀 Workflow Designer                               ⚠️  Degraded    │  │
│  │ v1.8.1 • Trial Enabled • 892 active users                         │  │
│  │ https://workflow-designer.riptide.example.com                     │  │
│  │ [View Details] [Edit] [Disable] [Rotate Credentials] [Analytics] │  │
│  │ ⚠️  Health check response time elevated (5.2s avg)                │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ 🧪 Rule Engine                                     ❌ Unhealthy    │  │
│  │ v2.5.0 • Premium Only • 0 active users                            │  │
│  │ https://rules.riptide.example.com                                 │  │
│  │ [View Details] [Edit] [Enable] [Rotate Credentials] [Analytics]  │  │
│  │ ❌ Health check failed: Connection timeout (3 consecutive)        │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  Showing 4 of 12 applications                           [1] 2 3 [Next]  │
└─────────────────────────────────────────────────────────────────────────┘

Application Registration Form

┌─────────────────────────────────────────────────────────────────────────┐
│  Register New Application                                                │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                                           │
│  Basic Information                                                        │
│  ─────────────────────────────────────────────────────────────────────  │
│                                                                           │
│  Application Name * (unique identifier, lowercase with hyphens)          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ ontology-manager                                                │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Display Name *                                                           │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Ontology Manager                                                │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Description * (10-500 characters)                                        │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Centralized ontology and taxonomy management system for         │    │
│  │ defining business concepts, relationships, and hierarchies.     │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Category *                                                               │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ [▼ Analytics]                                                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Network Configuration                                                    │
│  ─────────────────────────────────────────────────────────────────────  │
│                                                                           │
│  Base URL * (must be HTTPS for production)                                │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ https://ontology.riptide.example.com                            │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Health Check Endpoint * (relative path)                                  │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ /health                                                         │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Health Check Interval (seconds)                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ 60                                                              │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Version Information                                                      │
│  ─────────────────────────────────────────────────────────────────────  │
│                                                                           │
│  Current Version * (semantic versioning: MAJOR.MINOR.PATCH)              │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ 1.0.0                                                           │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Access Control                                                           │
│  ─────────────────────────────────────────────────────────────────────  │
│                                                                           │
│  ☑ Enable for Trial Users                                                │
│  ☐ Premium Users Only                                                    │
│                                                                           │
│  Dependencies (select applications this depends on)                       │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ ☑ Fee Manager (Required)                                        │    │
│  │ ☑ Value Manager (Required)                                      │    │
│  │ ☐ Workflow Designer (Optional)                                  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Additional Information (Optional)                                        │
│  ─────────────────────────────────────────────────────────────────────  │
│                                                                           │
│  Icon URL                                                                 │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ https://cdn.riptide.example.com/icons/ontology.svg             │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Documentation URL                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ https://docs.riptide.example.com/ontology-manager              │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Support Email                                                            │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ support-ontology@riptide.example.com                            │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  ┌──────────────────────┐                                                │
│  │  Register Application │  [Cancel]                                     │
│  └──────────────────────┘                                                │
│                                                                           │
│  * Required fields                                                        │
└─────────────────────────────────────────────────────────────────────────┘

Application Credentials Display (One-Time)

┌─────────────────────────────────────────────────────────────────────────┐
│  ✅ Application Registered Successfully!                                  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                                           │
│  Application: Ontology Manager                                            │
│  Application ID: 550e8400-e29b-41d4-a716-446655440000                    │
│                                                                           │
│  ⚠️  IMPORTANT: Copy these credentials NOW. They will not be shown again. │
│                                                                           │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ API Key                                                         │    │
│  │ RIPTIDE_5f7a9b2c4e8d1f3a6b9c2e5d8f1a4b7c  [📋 Copy]              │    │
│  │                                                                 │    │
│  │ API Secret                                                      │    │
│  │ a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0  │    │
│  │                                                         [📋 Copy] │    │
│  │                                                                 │    │
│  │ Webhook Secret                                                  │    │
│  │ webhook_9f8e7d6c5b4a3f2e1d9c8b7a6f5e4d3c  [📋 Copy]              │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  Next Steps:                                                              │
│  1. Securely store these credentials (password manager or vault)         │
│  2. Share with your application development team via secure channel      │
│  3. Configure credentials in application settings                         │
│  4. Test API connectivity: POST /api/v1/validate-credentials             │
│  5. Monitor health status in Application Registry dashboard              │
│                                                                           │
│  Integration Example:                                                     │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ curl -X POST \                                                  │    │
│  │   https://app-manager.riptide.example.com/api/v1/validate \     │    │
│  │   -H "X-Api-Key: RIPTIDE_5f7a9b2c4e8d1f3a6b9c2e5d8f1a4b7c" \    │    │
│  │   -H "X-Api-Key: [secret]"                                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                           │
│  ┌──────────────────────┐  ┌──────────────────────┐                     │
│  │  Download as JSON     │  │  Go to Application   │  [Close]            │
│  └──────────────────────┘  └──────────────────────┘                     │
└─────────────────────────────────────────────────────────────────────────┘

Application Details View

┌─────────────────────────────────────────────────────────────────────────┐
│  ← Back to Registry          Fee Manager                                 │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━   │
│                                                                           │
│  Status: ✅ Healthy  Version: v2.1.5  Active Users: 1,247                │
│  [Edit] [Disable] [Rotate Credentials] [View Logs] [Export Config]      │
│                                                                           │
│  ┌─────────────────────────┐  ┌─────────────────────────┐               │
│  │ Overview                │  │ Health Status           │               │
│  ├─────────────────────────┤  ├─────────────────────────┤               │
│  │ Name: fee-manager       │  │ Status: Healthy ✅      │               │
│  │ Display: Fee Manager    │  │ Last Check: 30s ago     │               │
│  │ Category: Finance       │  │ Response Time: 145ms    │               │
│  │ Trial Enabled: Yes      │  │ Uptime: 99.98%         │               │
│  │ Premium Only: No        │  │ Consecutive Fails: 0    │               │
│  │ Created: Jan 15, 2026   │  │ [View Health History]   │               │
│  └─────────────────────────┘  └─────────────────────────┘               │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Usage Statistics (Last 30 Days)                                   │  │
│  ├───────────────────────────────────────────────────────────────────┤  │
│  │ Total API Calls: 2,547,890                                        │  │
│  │ Success Rate: 99.94%                                              │  │
│  │ Average Response Time: 187ms                                      │  │
│  │ Peak Concurrent Users: 342                                        │  │
│  │                                                                   │  │
│  │ [Daily API Calls Graph]                                           │  │
│  │  █                                                                │  │
│  │  █  █                                                             │  │
│  │  █  █     █  █                                                    │  │
│  │  █  █  █  █  █  █  █                                             │  │
│  │ ─────────────────────────────────────────                        │  │
│  │  1   5   10  15  20  25  30 (days)                               │  │
│  │                                                                   │  │
│  │ [View Detailed Analytics]                                         │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ User Access                                                       │  │
│  ├───────────────────────────────────────────────────────────────────┤  │
│  │ Active Users: 1,247                                               │  │
│  │   • Trial Users: 423 (34%)                                        │  │
│  │   • Premium Users: 824 (66%)                                      │  │
│  │                                                                   │  │
│  │ Recent Access Grants:                                             │  │
│  │ • john.doe@example.com (Premium) - Granted Jan 28                │  │
│  │ • jane.smith@company.com (Trial) - Granted Jan 27                │  │
│  │ • bob.wilson@corp.com (Premium) - Granted Jan 26                 │  │
│  │                                                                   │  │
│  │ [View All Users] [Manage Access]                                  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Configuration                                                     │  │
│  ├───────────────────────────────────────────────────────────────────┤  │
│  │ Base URL: https://fee-manager.riptide.example.com                │  │
│  │ Health Check: /health (every 60s)                                 │  │
│  │ Documentation: https://docs.riptide.example.com/fee-manager      │  │
│  │ Support: support-fees@riptide.example.com                         │  │
│  │                                                                   │  │
│  │ API Credentials:                                                  │  │
│  │ • Active API Key: RIPTIDE_3a7f...4b8c (ends ...4b8c)             │  │
│  │ • Created: Jan 15, 2026                                           │  │
│  │ • Last Used: 2 minutes ago                                        │  │
│  │ • Usage Count: 2,547,890 calls                                    │  │
│  │ [Rotate Credentials]                                              │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Dependencies                                                      │  │
│  ├───────────────────────────────────────────────────────────────────┤  │
│  │ This application depends on:                                      │  │
│  │ • Value Manager (Required) - ✅ Healthy                           │  │
│  │ • Identity Service (Required) - ✅ Healthy                        │  │
│  │                                                                   │  │
│  │ Applications that depend on this:                                 │  │
│  │ • Workflow Designer (Integration) - ✅ Healthy                    │  │
│  │ • Reporting Service (Optional) - ✅ Healthy                       │  │
│  │                                                                   │  │
│  │ [Manage Dependencies]                                             │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                           │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │ Version History                                                   │  │
│  ├───────────────────────────────────────────────────────────────────┤  │
│  │ v2.1.5 (Current) - Deployed Jan 28, 2026                          │  │
│  │ v2.1.4 - Deployed Jan 20, 2026                                    │  │
│  │ v2.1.3 - Deployed Jan 10, 2026                                    │  │
│  │ [View Full History]                                               │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

API Endpoints

Register New Application

Endpoint: POST /api/v1/applications

Authentication: Bearer token (admin role required)

Request Body:

{
  "name": "ontology-manager",
  "displayName": "Ontology Manager",
  "description": "Centralized ontology and taxonomy management system for defining business concepts, relationships, and hierarchies.",
  "baseUrl": "https://ontology.riptide.example.com",
  "iconUrl": "https://cdn.riptide.example.com/icons/ontology.svg",
  "isTrialEnabled": true,
  "isPremiumOnly": false,
  "version": "1.0.0",
  "healthCheckEndpoint": "/health",
  "healthCheckIntervalSeconds": 60,
  "documentationUrl": "https://docs.riptide.example.com/ontology-manager",
  "supportEmail": "support-ontology@riptide.example.com",
  "category": "Analytics",
  "tags": ["ontology", "taxonomy", "metadata"],
  "dependencyIds": [
    "app-id-fee-manager",
    "app-id-value-manager"
  ]
}

Success Response: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "ontology-manager",
  "displayName": "Ontology Manager",
  "description": "Centralized ontology and taxonomy management system...",
  "baseUrl": "https://ontology.riptide.example.com",
  "iconUrl": "https://cdn.riptide.example.com/icons/ontology.svg",
  "isActive": true,
  "isTrialEnabled": true,
  "isPremiumOnly": false,
  "version": "1.0.0",
  "healthStatus": "Unknown",
  "createdAt": "2026-01-30T15:45:00Z",
  "credentials": {
    "apiKey": "RIPTIDE_5f7a9b2c4e8d1f3a6b9c2e5d8f1a4b7c",
    "apiSecret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
    "webhookSecret": "webhook_9f8e7d6c5b4a3f2e1d9c8b7a6f5e4d3c",
    "warning": "Store these credentials securely. They will not be displayed again."
  },
  "dependencies": [
    {
      "dependsOnApplicationId": "app-id-fee-manager",
      "dependsOnApplicationName": "Fee Manager",
      "dependencyType": "Required"
    },
    {
      "dependsOnApplicationId": "app-id-value-manager",
      "dependsOnApplicationName": "Value Manager",
      "dependencyType": "Required"
    }
  ],
  "message": "Application registered successfully. Initial health check scheduled."
}

Error Responses:

400 Bad Request - Validation error

{
  "error": "ValidationError",
  "message": "One or more validation errors occurred",
  "errors": {
    "name": ["Application name already exists"],
    "baseUrl": ["Production URLs must use HTTPS protocol"],
    "version": ["Version must follow semantic versioning format (e.g., 1.2.3)"],
    "dependencyIds": ["Circular dependency detected: ontology-manager -> fee-manager -> ontology-manager"]
  }
}

401 Unauthorized - Missing or invalid authentication

{
  "error": "Unauthorized",
  "message": "Authentication required to register applications"
}

403 Forbidden - Insufficient permissions

{
  "error": "Forbidden",
  "message": "Administrator role required to register applications"
}

409 Conflict - Duplicate application name

{
  "error": "DuplicateApplication",
  "message": "An application with this name already exists",
  "existingApplicationId": "existing-app-id",
  "existingApplicationStatus": "Active"
}

424 Failed Dependency - Health check failed (strict mode)

{
  "error": "HealthCheckFailed",
  "message": "Initial health check failed. Application cannot be registered.",
  "healthCheckUrl": "https://ontology.riptide.example.com/health",
  "errorDetails": "Connection timeout after 10 seconds",
  "suggestion": "Verify the application is running and the health endpoint is accessible"
}

List All Applications

Endpoint: GET /api/v1/applications

Authentication: Bearer token (admin role or valid session)

Query Parameters:

  • status (optional): Filter by status (active, inactive, archived)
  • trialEnabled (optional): Filter by trial eligibility (true/false)
  • category (optional): Filter by category
  • healthStatus (optional): Filter by health status (healthy, degraded, unhealthy)
  • search (optional): Search by name or description
  • page (optional): Page number (default: 1)
  • pageSize (optional): Items per page (default: 20, max: 100)
  • sortBy (optional): Sort field (name, createdAt, activeUsers)
  • sortOrder (optional): Sort direction (asc, desc)

Example Request:

GET /api/v1/applications?status=active&trialEnabled=true&sortBy=activeUsers&sortOrder=desc

Success Response: 200 OK

{
  "applications": [
    {
      "id": "app-id-fee-manager",
      "name": "fee-manager",
      "displayName": "Fee Manager",
      "description": "Comprehensive fee calculation and management system",
      "baseUrl": "https://fee-manager.riptide.example.com",
      "iconUrl": "https://cdn.riptide.example.com/icons/fee-manager.svg",
      "isActive": true,
      "isTrialEnabled": true,
      "isPremiumOnly": false,
      "version": "2.1.5",
      "healthStatus": "Healthy",
      "lastHealthCheckAt": "2026-01-30T15:44:30Z",
      "category": "Finance",
      "totalUsers": 1247,
      "totalApiCalls": 2547890,
      "lastApiCallAt": "2026-01-30T15:44:45Z",
      "createdAt": "2026-01-15T10:00:00Z"
    },
    {
      "id": "app-id-value-manager",
      "name": "value-manager",
      "displayName": "Value Manager",
      "description": "Dynamic value management and calculation engine",
      "baseUrl": "https://value-manager.riptide.example.com",
      "iconUrl": "https://cdn.riptide.example.com/icons/value-manager.svg",
      "isActive": true,
      "isTrialEnabled": true,
      "isPremiumOnly": false,
      "version": "3.0.2",
      "healthStatus": "Healthy",
      "lastHealthCheckAt": "2026-01-30T15:44:15Z",
      "category": "Finance",
      "totalUsers": 523,
      "totalApiCalls": 1234567,
      "lastApiCallAt": "2026-01-30T15:43:22Z",
      "createdAt": "2026-01-18T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "totalItems": 2
  }
}

Get Application Details

Endpoint: GET /api/v1/applications/{id}

Authentication: Bearer token (admin role or valid session)

Success Response: 200 OK

{
  "id": "app-id-fee-manager",
  "name": "fee-manager",
  "displayName": "Fee Manager",
  "description": "Comprehensive fee calculation and management system",
  "baseUrl": "https://fee-manager.riptide.example.com",
  "iconUrl": "https://cdn.riptide.example.com/icons/fee-manager.svg",
  "isActive": true,
  "isTrialEnabled": true,
  "isPremiumOnly": false,
  "version": "2.1.5",
  "healthCheckEndpoint": "/health",
  "healthCheckIntervalSeconds": 60,
  "healthStatus": "Healthy",
  "lastHealthCheckAt": "2026-01-30T15:44:30Z",
  "consecutiveFailures": 0,
  "documentationUrl": "https://docs.riptide.example.com/fee-manager",
  "supportEmail": "support-fees@riptide.example.com",
  "category": "Finance",
  "tags": ["fees", "calculation", "billing"],
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-01-28T09:15:00Z",
  "createdBy": "admin-user-id",
  "totalUsers": 1247,
  "trialUsers": 423,
  "premiumUsers": 824,
  "totalApiCalls": 2547890,
  "lastApiCallAt": "2026-01-30T15:44:45Z",
  "credentials": {
    "activeApiKey": "RIPTIDE_3a7f...4b8c",
    "createdAt": "2026-01-15T10:00:00Z",
    "lastUsedAt": "2026-01-30T15:44:45Z",
    "usageCount": 2547890,
    "note": "Full secret not displayed for security. Use rotate endpoint to generate new credentials."
  },
  "dependencies": [
    {
      "dependsOnApplicationId": "app-id-value-manager",
      "dependsOnApplicationName": "Value Manager",
      "dependencyType": "Required",
      "dependencyHealthStatus": "Healthy"
    }
  ],
  "dependents": [
    {
      "applicationId": "app-id-workflow-designer",
      "applicationName": "Workflow Designer",
      "dependencyType": "Integration"
    }
  ],
  "versionHistory": [
    {
      "version": "2.1.5",
      "deployedAt": "2026-01-28T09:15:00Z",
      "deployedBy": "admin-user-id"
    },
    {
      "version": "2.1.4",
      "deployedAt": "2026-01-20T11:30:00Z",
      "deployedBy": "admin-user-id"
    }
  ],
  "usageStatistics": {
    "last30Days": {
      "totalApiCalls": 2547890,
      "successRate": 99.94,
      "averageResponseTimeMs": 187,
      "peakConcurrentUsers": 342,
      "errorRate": 0.06
    }
  }
}

Update Application

Endpoint: PUT /api/v1/applications/{id}

Authentication: Bearer token (admin role required)

Request Body:

{
  "displayName": "Fee Manager Pro",
  "description": "Updated comprehensive fee calculation and management system with advanced features",
  "baseUrl": "https://fee-manager-v2.riptide.example.com",
  "iconUrl": "https://cdn.riptide.example.com/icons/fee-manager-v2.svg",
  "isTrialEnabled": false,
  "isPremiumOnly": true,
  "version": "2.2.0",
  "healthCheckIntervalSeconds": 30,
  "documentationUrl": "https://docs.riptide.example.com/fee-manager-v2",
  "supportEmail": "support-fees-premium@riptide.example.com",
  "dependencyIds": [
    "app-id-value-manager",
    "app-id-rule-engine"
  ]
}

Success Response: 200 OK

{
  "id": "app-id-fee-manager",
  "name": "fee-manager",
  "displayName": "Fee Manager Pro",
  "description": "Updated comprehensive fee calculation and management system with advanced features",
  "version": "2.2.0",
  "updatedAt": "2026-01-30T16:00:00Z",
  "updatedBy": "admin-user-id",
  "message": "Application updated successfully",
  "changes": [
    "Display name changed from 'Fee Manager' to 'Fee Manager Pro'",
    "Version updated from 2.1.5 to 2.2.0",
    "Trial access disabled - existing trial users will retain access until expiration",
    "Added dependency: Rule Engine",
    "Health check interval changed from 60s to 30s"
  ]
}

Enable/Disable Application

Endpoint: POST /api/v1/applications/{id}/disable
Endpoint: POST /api/v1/applications/{id}/enable

Authentication: Bearer token (admin role required)

Request Body (for disable):

{
  "reason": "Maintenance scheduled for system upgrade",
  "notifyUsers": true,
  "gracePeriodMinutes": 15
}

Success Response: 200 OK

{
  "id": "app-id-fee-manager",
  "name": "fee-manager",
  "isActive": false,
  "disabledAt": "2026-01-30T16:05:00Z",
  "disabledBy": "admin-user-id",
  "reason": "Maintenance scheduled for system upgrade",
  "activeUserCount": 42,
  "message": "Application disabled successfully. 42 active users have been notified with 15-minute grace period."
}

Rotate API Credentials

Endpoint: POST /api/v1/applications/{id}/rotate-credentials

Authentication: Bearer token (admin role required)

Request Body:

{
  "gracePeriodHours": 24,
  "notifyTeam": true,
  "reason": "Scheduled credential rotation"
}

Success Response: 200 OK

{
  "id": "app-id-fee-manager",
  "name": "fee-manager",
  "newCredentials": {
    "apiKey": "RIPTIDE_9d3e7a2f5c8b1e4a7d0c3f6b9e2a5d8c",
    "apiSecret": "z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0f9e8d7c6b5a4z3y2x1w0v9u8",
    "webhookSecret": "webhook_f5e4d3c2b1a9f8e7d6c5b4a3f2e1d0c9",
    "warning": "Store these credentials securely. They will not be displayed again."
  },
  "oldCredentials": {
    "apiKey": "RIPTIDE_3a7f...4b8c",
    "expiresAt": "2026-01-31T16:10:00Z",
    "gracePeriodHours": 24,
    "status": "Deprecated"
  },
  "rotatedAt": "2026-01-30T16:10:00Z",
  "rotatedBy": "admin-user-id",
  "reason": "Scheduled credential rotation",
  "message": "Credentials rotated successfully. Old credentials will remain valid for 24 hours. Team notified via email."
}

Archive Application

Endpoint: POST /api/v1/applications/{id}/archive

Authentication: Bearer token (admin role required)

Request Body:

{
  "reason": "Application deprecated in favor of new platform",
  "notifyUsers": true,
  "exportData": true
}

Success Response: 200 OK

{
  "id": "app-id-legacy-calculator",
  "name": "legacy-calculator",
  "status": "Archived",
  "archivedAt": "2026-01-30T16:15:00Z",
  "archivedBy": "admin-user-id",
  "reason": "Application deprecated in favor of new platform",
  "dataExport": {
    "url": "https://exports.riptide.example.com/legacy-calculator-2026-01-30.zip",
    "expiresAt": "2026-02-06T16:15:00Z"
  },
  "affectedUsers": 15,
  "message": "Application archived successfully. All API credentials revoked. 15 users notified. Data export available for 7 days."
}

Error Response (has dependencies): 400 Bad Request

{
  "error": "CannotArchive",
  "message": "Cannot archive application. Other applications depend on it.",
  "dependentApplications": [
    {
      "id": "app-id-workflow-designer",
      "name": "workflow-designer",
      "displayName": "Workflow Designer",
      "dependencyType": "Required"
    }
  ],
  "suggestion": "Remove or update dependencies before archiving this application"
}

Validate Application Credentials

Endpoint: POST /api/v1/applications/validate-credentials

Authentication: Custom (API Key + Secret in headers)

Headers:

X-Api-Key: RIPTIDE_5f7a9b2c4e8d1f3a6b9c2e5d8f1a4b7c
X-Api-Key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0

Success Response: 200 OK

{
  "valid": true,
  "applicationId": "550e8400-e29b-41d4-a716-446655440000",
  "applicationName": "ontology-manager",
  "credentialsType": "Active",
  "expiresAt": null,
  "message": "Credentials validated successfully"
}

Error Response: 401 Unauthorized

{
  "valid": false,
  "error": "InvalidCredentials",
  "message": "API credentials are invalid or have been revoked",
  "suggestion": "Contact administrator to rotate credentials"
}

Get Application Usage Statistics

Endpoint: GET /api/v1/applications/{id}/statistics

Authentication: Bearer token (admin role required)

Query Parameters:

  • startDate (optional): Start date for statistics (ISO 8601)
  • endDate (optional): End date for statistics (ISO 8601)
  • granularity (optional): hour, day, week, month (default: day)

Example Request:

GET /api/v1/applications/app-id-fee-manager/statistics?startDate=2026-01-01&endDate=2026-01-30&granularity=day

Success Response: 200 OK

{
  "applicationId": "app-id-fee-manager",
  "applicationName": "fee-manager",
  "periodStart": "2026-01-01T00:00:00Z",
  "periodEnd": "2026-01-30T23:59:59Z",
  "granularity": "day",
  "summary": {
    "totalApiCalls": 2547890,
    "averageSuccessRate": 99.94,
    "averageResponseTimeMs": 187,
    "peakConcurrentUsers": 342,
    "totalUniqueUsers": 1247,
    "newUsersAdded": 187,
    "averageErrorRate": 0.06
  },
  "dailyStatistics": [
    {
      "date": "2026-01-30",
      "activeUsers": 1247,
      "newUsers": 12,
      "trialUsers": 423,
      "premiumUsers": 824,
      "totalApiCalls": 98543,
      "successfulCalls": 98487,
      "failedCalls": 56,
      "averageResponseTimeMs": 182,
      "peakConcurrentUsers": 89,
      "errorRate": 0.06
    },
    {
      "date": "2026-01-29",
      "activeUsers": 1235,
      "newUsers": 8,
      "trialUsers": 411,
      "premiumUsers": 824,
      "totalApiCalls": 95234,
      "successfulCalls": 95189,
      "failedCalls": 45,
      "averageResponseTimeMs": 185,
      "peakConcurrentUsers": 92,
      "errorRate": 0.05
    }
  ]
}

Get Application Users

Endpoint: GET /api/v1/applications/{id}/users

Authentication: Bearer token (admin role required)

Query Parameters:

  • accessType (optional): Filter by access type (trial, premium, admin)
  • status (optional): Filter by status (active, expired, revoked)
  • page (optional): Page number
  • pageSize (optional): Items per page

Success Response: 200 OK

{
  "applicationId": "app-id-fee-manager",
  "applicationName": "fee-manager",
  "users": [
    {
      "userId": "user-id-123",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "accessType": "Premium",
      "grantedAt": "2026-01-28T10:00:00Z",
      "expiresAt": null,
      "lastAccessAt": "2026-01-30T15:30:00Z",
      "isRevoked": false,
      "apiCallCount": 15234
    },
    {
      "userId": "user-id-456",
      "fullName": "Jane Smith",
      "email": "jane.smith@company.com",
      "accessType": "Trial",
      "grantedAt": "2026-01-27T14:22:00Z",
      "expiresAt": "2026-02-26T14:22:00Z",
      "lastAccessAt": "2026-01-30T14:15:00Z",
      "isRevoked": false,
      "apiCallCount": 523
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 63,
    "totalItems": 1247
  }
}

Application-to-Manager Communication Flow

sequenceDiagram participant App as Riptide Application participant LB as Load Balancer participant API as Application Manager API participant Cache as Redis Cache participant DB as Registry Database participant Monitor as Health Monitor Note over App,Monitor: Startup and Registration Verification App->>App: Application starts up App->>App: Load API credentials from config App->>API: POST /api/v1/applications/validate-credentials Note over App,API: Headers: X-Api-Key, X-Api-Key API->>Cache: Check credentials cache Cache-->>API: Cache miss API->>DB: Query credentials & application status DB->>API: Return credentials + app details API->>API: Verify credentials hash matches API->>Cache: Cache credentials (TTL: 5 min) API->>App: 200 OK - Credentials valid Note over App,Monitor: Health Check Flow Monitor->>App: GET /health (every 60s) App->>App: Check internal subsystems App->>App: Check database connectivity App->>App: Check external dependencies alt All Systems Healthy App->>Monitor: 200 OK {"status": "healthy", "version": "2.1.5"} Monitor->>DB: Update health status (Healthy) Monitor->>DB: Reset consecutive failures = 0 else Degraded Performance App->>Monitor: 200 OK {"status": "degraded", "details": "High load"} Monitor->>DB: Update health status (Degraded) Monitor->>Monitor: Log warning, don't increment failures else System Unhealthy App--xMonitor: Timeout or 500 error Monitor->>DB: Increment consecutive failures Monitor->>DB: Check if failures >= 3 alt Failure Threshold Exceeded Monitor->>DB: Update health status (Unhealthy) Monitor->>API: Trigger alert notification API->>App: Send diagnostic request (optional) end end Note over App,Monitor: User Session Validation participant User as User User->>App: Access application with session token App->>API: POST /api/v1/sessions/validate Note over App,API: Headers: X-Api-Key, X-Api-Key<br/>Body: {sessionToken, userId} API->>Cache: Check session cache Cache-->>API: Session found API->>API: Validate session not expired API->>API: Verify user has access to app alt Session Valid & User Has Access API->>App: 200 OK {sessionValid: true, userAccess: "premium"} App->>User: Grant application access App->>DB: Log usage (async) else Session Invalid or Expired API->>App: 401 Unauthorized {sessionValid: false} App->>User: Redirect to login else Session Valid but No Access API->>App: 403 Forbidden {sessionValid: true, userAccess: "none"} App->>User: Display "No access" message end Note over App,Monitor: Application Metrics Reporting App->>App: Collect metrics every 5 minutes App->>API: POST /api/v1/applications/{id}/metrics Note over App,API: Body: {timestamp, activeUsers,<br/>apiCalls, avgResponseTime, errors} API->>DB: Insert metrics record API->>App: 202 Accepted Note over App,Monitor: Credential Rotation Handling API->>App: POST /webhook/credentials-rotated Note over API,App: Webhook notification with<br/>new credential preview (last 4 chars) App->>App: Log credential rotation notice App->>App: Set alert for admin App-->>API: 200 OK (acknowledged) Note over App: Admin updates app config<br/>with new credentials App->>App: Reload configuration App->>API: POST /api/v1/applications/validate-credentials Note over App,API: Using new credentials API->>App: 200 OK - New credentials validated App->>App: Mark old credentials for removal Note over App,Monitor: Application Shutdown App->>App: Receive shutdown signal App->>Monitor: Final health check response Note over Monitor: Monitor detects no response<br/>after 3 checks, marks unhealthy App->>API: POST /api/v1/applications/{id}/status Note over App,API: Body: {status: "shutting_down"} API->>DB: Update application status API->>Monitor: Pause health checks for this app API->>App: 200 OK App->>App: Complete shutdown

Performance Requirements

Metric Target Critical Threshold
Application registration time < 3 seconds < 10 seconds
Credential validation time < 100ms (cached), < 500ms (uncached) < 2 seconds
Health check execution time < 10 seconds per application < 30 seconds
Health check monitoring all apps Complete all checks within interval Delayed checks acceptable
Application list query time < 500ms < 2 seconds
Application details query time < 300ms < 1 second
Credential rotation time < 2 seconds < 5 seconds
Database query performance < 100ms for simple queries < 500ms
Concurrent validation requests supported 1000/second 500/second
API endpoint response time (95th percentile) < 500ms < 2 seconds

Security Considerations

Credential Security

  • API keys and secrets must be cryptographically random (use System.Security.Cryptography.RandomNumberGenerator)
  • API secrets must NEVER be stored in plain text (use bcrypt or Argon2 hashing)
  • API secrets displayed only once during initial registration or rotation
  • Credentials must be transmitted only over HTTPS
  • Credentials should never be logged in plain text
  • Credential rotation should be enforced (recommendation: every 365 days)
  • Grace period for old credentials prevents service disruption

Access Control

  • Application registration requires administrator role
  • Application updates require administrator role
  • Credential rotation requires administrator role
  • Application archival requires administrator role
  • Non-admin users can view application list but not credentials
  • Applications use dedicated API key authentication (separate from user auth)

Health Check Security

  • Health check endpoints should not expose sensitive information
  • Health check responses should be standardized across applications
  • Failed health checks should not leak internal error details
  • Health monitoring should use separate network path if possible

Data Protection

  • Application credentials encrypted at rest
  • Webhook secrets encrypted at rest
  • Audit trail maintained for all application operations
  • Sensitive data redacted from logs (credentials, secrets)
  • Application configuration exports should exclude credentials

Rate Limiting

  • Credential validation endpoint: 100 requests/minute per application
  • Health check failures trigger exponential backoff
  • Maximum 5 credential rotations per application per day (prevent abuse)

Dependency Validation

  • Circular dependency detection prevents deadlocks
  • Dependency health status checked before critical operations
  • Cascading failures minimized through dependency isolation

Testing Scenarios

Test Case 1: Successful Application Registration

Given: Valid application data with accessible health check endpoint
When: Administrator submits registration form
Then: Application created, credentials generated, health check registered, 201 response returned
Verify: Database record exists, credentials work, health monitoring active

Test Case 2: Duplicate Application Name Prevention

Given: Application name already exists in registry
When: Administrator attempts to register with same name
Then: 409 Conflict returned
Verify: No duplicate application created, appropriate error message displayed

Test Case 3: Health Check Failure Handling (Permissive Mode)

Given: Health check endpoint not accessible, permissive mode enabled
When: Administrator registers application
Then: Application created with "Unhealthy" status, warning displayed
Verify: Application exists, health monitoring continues retry attempts

Test Case 4: Health Check Failure Blocking (Strict Mode)

Given: Health check endpoint not accessible, strict mode enabled
When: Administrator registers application
Then: 424 Failed Dependency returned, registration blocked
Verify: No application created, diagnostic information provided

Test Case 5: Circular Dependency Detection

Given: Application A depends on B, Application B depends on C, attempt to make C depend on A
When: Administrator updates Application C dependencies
Then: 400 Bad Request returned with circular dependency error
Verify: Dependency not created, existing dependencies unchanged

Test Case 6: Credential Rotation with Grace Period

Given: Application with active credentials
When: Administrator rotates credentials with 24-hour grace period
Then: New credentials generated, old credentials deprecated
Verify: Both old and new credentials work initially, old credentials expire after 24 hours

Test Case 7: Application Disable with Active Users

Given: Application has 50 active user sessions
When: Administrator disables application
Then: Confirmation dialog shown, application disabled after confirmation
Verify: Active users notified, new access attempts denied, application status = inactive

Test Case 8: Archive with Dependencies Blocked

Given: Application B depends on Application A
When: Administrator attempts to archive Application A
Then: 400 Bad Request returned listing dependents
Verify: Application A remains active, error message lists dependencies

Test Case 9: Successful Application Archive

Given: Application with no dependencies, no active users
When: Administrator archives application
Then: Application archived, credentials revoked, data exported
Verify: Status = archived, credentials invalid, audit history preserved

Test Case 10: Credential Validation Performance

Given: 1000 concurrent credential validation requests
When: Applications startup simultaneously
Then: All validations complete within performance threshold
Verify: Cache hit rate > 80% after initial requests, no database overload

Test Case 11: Health Check Consecutive Failure Threshold

Given: Application returns 500 error on health checks
When: 3 consecutive health checks fail
Then: Application marked as "Unhealthy", alert triggered
Verify: Health status updated after 3rd failure, administrator notified

Test Case 12: Version Update Tracking

Given: Application currently at v1.5.2
When: Administrator updates version to v1.5.3
Then: Version updated, version history recorded
Verify: Current version = 1.5.3, version history includes both versions with timestamps

Monitoring and Analytics

Key Metrics to Track

  • Registration Rate: Number of new applications registered per month
  • Active Applications: Count of applications with IsActive = true
  • Health Status Distribution: Breakdown of applications by health status (Healthy, Degraded, Unhealthy)
  • Average Health Check Response Time: Monitor performance across all applications
  • Health Check Failure Rate: Percentage of failed health checks per application
  • Credential Rotation Frequency: Track credential age and rotation compliance
  • API Call Volume: Total API calls across all applications
  • User Access Distribution: Users per application (identify most/least popular apps)
  • Dependency Complexity: Average dependencies per application
  • Application Uptime: Percentage of time each application is healthy

Application-Specific Dashboards

Each application should have dedicated dashboard showing:

  • Real-time health status
  • 24-hour API call volume chart
  • Active user count (current)
  • Success rate vs. error rate (last 7 days)
  • Average response time trend
  • Top errors (if any)
  • Dependency health status
  • Recent version deployments

Alerts

  • Application health check fails 3 consecutive times (trigger: immediate)
  • Application health check response time > 5 seconds (trigger: after 10 occurrences)
  • Credential age > 350 days (trigger: warning for rotation planning)
  • Credential expires within 7 days (trigger: critical alert)
  • Application API call volume drops > 50% in 1 hour (potential outage)
  • Application error rate > 5% in 15 minutes (degraded service)
  • New application registered (informational notification)
  • Application archived (informational notification)
  • Dependency health issue affecting dependent apps (cascade warning)

Audit Trail

All application operations logged with:

  • Timestamp (UTC)
  • Administrator user ID
  • Operation type (Register, Update, Disable, Enable, Archive, Rotate Credentials)
  • Application ID and name
  • Old values (for updates)
  • New values (for updates)
  • Reason (if provided)
  • IP address of request
  • Request ID for tracing
  • UC-001: Trial User Self-Registration and Access (users gain access to trial-enabled applications)
  • UC-002: Trial User Login and Session Management (session validation by applications)
  • UC-003: Application Health Monitoring and Alerting
  • UC-004: Application Analytics and Reporting
  • UC-005: Administrator Application Access Management
  • UC-006: Application Credential Management and Rotation
  • UC-007: Application Version Tracking and Deployment History
  • UC-008: Application Dependency Management
  • UC-009: Application Usage Quotas and Throttling
  • UC-010: Premium User Application Access Control
  • UC-011: Application API Gateway Configuration
  • UC-012: Multi-Tenant Application Isolation

Notes and Assumptions

  1. HTTPS Required: Production applications must use HTTPS; HTTP allowed only for local development
  2. Health Check Standardization: All applications must implement standardized health check endpoint returning JSON with status and version
  3. Credential Display: API secrets shown only once (at generation); cannot be retrieved later, only rotated
  4. No Physical Deletion: Applications are archived, never deleted (audit trail preservation)
  5. Grace Period Standard: Default 24-hour grace period for credential rotation balances security with operational flexibility
  6. Dependency Limit: Maximum 10 dependencies per application prevents overly complex dependency graphs
  7. Circular Dependencies: Not allowed; detected and blocked during registration/update
  8. Health Check Timeout: Fixed 10-second timeout for health checks (configurable globally, not per-app)
  9. Trial Eligibility: Applications marked trial-enabled can be accessed by trial users without upgrade
  10. Premium Only: Applications marked premium-only require paid subscription (trial users cannot access)
  11. Version Format: Semantic versioning required (MAJOR.MINOR.PATCH, optional pre-release suffix)
  12. Auto-Monitoring: Health monitoring starts automatically upon registration; no manual activation needed
  13. Application Isolation: Each application maintains separate credentials; no shared keys across applications

Revision History

Version Date Author Changes
1.0 2026-01-30 Platform Architecture Team Initial comprehensive use case documentation for application registration and management

Document Owner: Platform Architecture Team
Stakeholders: DevOps Engineering, Platform Administration, Application Development Teams, Security Team
Review Cycle: Quarterly or as needed for major platform changes