Skip to main content

Business Central Admin Center API - Feature Analysis & Recommendations

Executive Summary​

This document analyzes the Microsoft Business Central Admin Center API (latest version v2.28) and provides recommendations for enhancing the Admin Hub BCAdminCenter plugin based on available API capabilities.

Analysis Date: December 4, 2025
API Documentation: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api
Current API Version Used: v2.21
Latest Available Version: v2.28

1. API Version Update​

Current State​

  • Admin Hub uses API version v2.21
  • Located in: BCAdminCenter\src\Connection\ConnectionClient.Codeunit.al (line 46)

Recommendation​

Priority: HIGH

  • Update to v2.28 to access latest features and improvements
  • Version 2.28 includes features up to November 2025

Implementation​

// Update from:
BaseUrlTok: Label 'https://api.businesscentral.dynamics.com/admin/v2.21%1'

// To:
BaseUrlTok: Label 'https://api.businesscentral.dynamics.com/admin/v2.28%1'

2. Environment Management Features​

2.1 Environment Recovery (API v2.18+)​

Status: ❌ NOT IMPLEMENTED
Priority: HIGH

Feature Description​

  • Recover soft-deleted environments within 14-day retention period
  • Soft delete functionality was introduced to prevent accidental permanent deletions

API Endpoints​

POST /admin/v2.28/applications/{applicationFamily}/environments/{environmentName}/recover

Implementation Recommendations​

  1. Add Recover action to environment list and card pages
  2. Track soft-deleted environments with additional status values
  3. Add fields to TenantEnvironment_TSL table:
    • SoftDeletedOn (DateTime)
    • HardDeletePendingOn (DateTime)
    • DeleteReason (Text[100])
  4. Show visual indicators for soft-deleted environments (e.g., strikethrough, different color)
  5. Add factbox showing days remaining before permanent deletion

Benefits​

  • Prevent accidental data loss
  • Provide safety net for admin mistakes
  • Align with Microsoft's best practices

2.2 Point-in-Time Restore (API v2.4+)​

Status: ❌ NOT IMPLEMENTED
Priority: HIGH

Feature Description​

  • Restore environment to a specific point in time
  • Useful for data recovery, testing, and compliance

API Endpoints​

POST /admin/v2.28/applications/{applicationFamily}/environments/{environmentName}/restore
GET /admin/v2.28/applications/{applicationFamily}/environments/{environmentName}/availableRestorePeriods

Request Body​

{
  "EnvironmentName": "restored-env",
  "EnvironmentType": "production",
  "PointInTime": "2025-12-04T20:00:00Z",
  "SkipInstallingPTEs": true,
  "SkipInstallingThirdPartyGlobalApps": true,
  "SkipEnvironmentCleanup": true
}

Implementation Recommendations​

  1. Add Restore Environment action
  2. Create wizard page for restore options:
    • New environment name
    • Environment type (Production/Sandbox)
    • Point-in-time selection (date/time picker)
    • Options to skip PTEs and third-party apps
    • Cleanup options
  3. Display available restore periods with corresponding application versions
  4. Track restore operations in TenantEnvOp_TSL table

Benefits​

  • Data recovery capabilities
  • Testing scenarios with production data at specific points
  • Compliance and audit requirements

2.3 Environment Storage Monitoring (API v2.26+)​

Status: ⚠️ PARTIALLY IMPLEMENTED
Priority: MEDIUM

Current Implementation​

  • No evidence of storage monitoring in current codebase

Feature Description​

  • Monitor database storage usage per environment
  • Track total storage quotas and limits
  • API v2.26+ supports 64-bit integers for large databases

API Endpoints​

GET /admin/v2.28/applications/{applicationFamily}/environments/{environmentName}/usedstorage
GET /admin/v2.28/environments/usedstorage
GET /admin/v2.28/environments/quotas

Response Structure​

{
  "environmentType": "Production",
  "environmentName": "Production",
  "applicationFamily": "BusinessCentral",
  "databaseStorageInKilobytes": 5242880
}

// Quotas response
{
  "environmentsCount": {
    "production": 3,
    "sandbox": 10
  },
  "storageInKilobytes": {
    "default": 10485760,
    "userLicenses": 52428800,
    "additionalCapacity": 104857600,
    "total": 167772160
  }
}

Implementation Recommendations​

  1. Add storage fields to TenantEnvironment_TSL:
    • DatabaseStorageInKB (BigInteger)
    • LastStorageCheckDateTime (DateTime)
  2. Add tenant-level storage tracking table:
    • Total storage quota
    • Used storage across all environments
    • Available storage
  3. Create storage monitoring FactBox showing:
    • Storage usage per environment
    • Percentage of quota used
    • Storage trends
  4. Add alerts for high storage usage (e.g., >80%)
  5. Schedule periodic storage checks (daily/weekly)

Benefits​

  • Proactive capacity planning
  • Identify storage-intensive environments
  • Optimize costs
  • Prevent service disruptions

2.4 Power Platform Integration (API v2.21+)​

Status: ❌ NOT IMPLEMENTED
Priority: MEDIUM

Feature Description​

  • Link/unlink Business Central environments with Power Platform environments
  • Enable integrated scenarios with Power Apps, Power Automate, Power BI

API Endpoints​

POST /admin/v2.28/bap/applications/{applicationFamily}/environments/{environmentName}/linkEnvironment?powerPlatformEnvironmentId={id}
POST /admin/v2.28/bap/applications/{applicationFamily}/environments/{environmentName}/unlinkEnvironment?powerPlatformEnvironmentId={id}

Important Notes​

  • NOT supported for service-to-service authentication (requires delegated auth)
  • Environments must be same type (Production/Sandbox)
  • Must be in same Azure Geo

Implementation Recommendations​

  1. Add Power Platform integration fields to TenantEnvironment_TSL:
    • PowerPlatformEnvID (Text[100])
    • PowerPlatformLinked (Boolean)
  2. Add Link/Unlink actions (only visible when using delegated auth)
  3. Show warning about authentication requirements
  4. Display linked Power Platform environment info in FactBox

Benefits​

  • Enable low-code/no-code integrations
  • Unlock Power Platform capabilities
  • Unified admin experience

2.5 Environment Settings Management​

Status: ⚠️ PARTIALLY IMPLEMENTED
Priority: MEDIUM

Currently Implemented​

  • Update window settings (start/end time, time zone)
  • Scheduled updates (reschedule)
  • Ignore upgrade window flag

Missing Features​

  1. Application Insights Key Management
  2. Security Group Management (Microsoft Entra groups)
  3. Microsoft 365 License Access Settings (API v2.12+)
  4. AppSource Apps Update Cadence

API Endpoints (Missing)​

PUT /admin/v2.28/applications/{applicationFamily}/environments/{environmentName}/settings/appinsightskey
PUT /admin/v2.28/applications/{applicationFamily}/environments/{environmentName}/settings/securityGroupId
DELETE /admin/v2.28/applications/{applicationFamily}/environments/{environmentName}/settings/securityGroupId

Implementation Recommendations​

  1. Add fields to TenantEnvironment_TSL:
    • AppInsightsKey (Text[250])
    • SecurityGroupId (Text[100])
    • SecurityGroupName (Text[250])
    • M365LicenseAccessEnabled (Boolean)
    • AppSourceAppsUpdateCadence (Option: 'Default','WithPlatformUpdates','Never')
  2. Create settings management page/dialog
  3. Add actions for:
    • Set Application Insights Key
    • Manage Security Groups
    • Configure M365 License Access
    • Set AppSource Update Cadence

Benefits​

  • Complete environment configuration from Admin Hub
  • Better security management
  • Telemetry integration
  • Flexible licensing options

2.6 Enhanced Environment Versioning​

Status: ⚠️ PARTIALLY IMPLEMENTED
Priority: LOW

Current Implementation​

  • Basic version tracking in ApplicationVersion field

Missing Features (API v2.21+)​

  • Detailed version information with grace periods
  • Enforced update period tracking

API Response Structure​

{
  "versionDetails": {
    "version": "26.0",
    "gracePeriodStartDate": "2025-10-01T00:00:00Z",
    "enforcedUpdatePeriodStartDate": "2025-11-01T00:00:00Z"
  }
}

Implementation Recommendations​

  1. Add fields to TenantEnvironment_TSL:
    • VersionMajor (Integer)
    • VersionMinor (Integer)
    • GracePeriodStartDate (DateTime)
    • EnforcedUpdatePeriodStartDate (DateTime)
  2. Show visual indicators for environments in:
    • Grace period (warning)
    • Enforced update period (critical)
  3. Add alerts/notifications for version lifecycle stages

3. App Management Features​

3.1 Enhanced Operation Tracking​

Status: ⚠️ PARTIALLY IMPLEMENTED
Priority: MEDIUM

Currently Implemented​

  • Basic operation tracking for environment operations
  • Support for some operation types

Missing Operation Types (needs verification)​

The following operation types should be tracked according to API v2.6+:

  • EnvironmentAppHotfix (API v2.6+)
  • MoveToAnotherAadTenant (move environments between tenants)
  • Modify (various settings changes)
  • Update (long-running background updates)
  • Restart (API v2.10+)
  • SoftDelete and Recover (API v2.17+)

Implementation Recommendations​

  1. Review TenantEnvOp_TSL table to ensure all operation types are supported
  2. Add operation type enum values if missing
  3. Enhance operation detail display for each type
  4. Add operation-specific parameters tracking

3.2 App Hotfix Support (API v2.6+)​

Status: ❌ NOT IMPLEMENTED
Priority: LOW

Feature Description​

  • Track hotfix operations for apps
  • Different from regular updates

Implementation Recommendations​

  1. Add hotfix tracking to operation history
  2. Display hotfix indicator on app cards
  3. Track hotfix version separately from regular version

4. Authentication & Security​

4.1 Certificate-Based Authentication​

Status: ❌ NOT IMPLEMENTED
Priority: HIGH (Security Best Practice)

Current State​

  • Only client secret authentication implemented
  • Client credentials flow with secrets

Microsoft Recommendation​

Microsoft strongly recommends using X.509 certificates instead of client secrets for production scenarios.

Reference: Identity Platform Security Checklist

Implementation Recommendations​

  1. Add certificate-based authentication option in connection setup
  2. Support both client secret (dev/test) and certificate (production)
  3. Add certificate management UI:
    • Upload certificate (.pfx)
    • Certificate expiry tracking
    • Certificate renewal reminders
  4. Update authentication token acquisition to support certificates

PowerShell Example (from MS docs)​

$cred = [Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential]::new($AppId, $Certificate)
$ctx = [Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext]::new("https://login.windows.net/$TenantName")
$token = $ctx.AcquireTokenAsync("996def3d-b36c-4153-8607-a6fd3c01b89f", $cred).GetAwaiter().GetResult().AccessToken

Benefits​

  • Enhanced security (no secrets to rotate/leak)
  • Compliance with security best practices
  • Better audit trail
  • Longer validity periods

4.2 Delegated Admin Access Support​

Status: ❓ UNKNOWN
Priority: MEDIUM

Feature Description​

For Cloud Solution Provider (CSP) partners managing customer tenants

Requirements​

Implementation Recommendations​

  1. Document delegated admin setup process
  2. Add validation for AdminAgents group membership
  3. Provide guidance for CSP partners
  4. Add CSP-specific connection setup workflow

5. Error Handling & Resilience​

5.1 Standardized Error Response Handling​

Status: ⚠️ NEEDS REVIEW
Priority: MEDIUM

API Error Format​

{
  "code": "EnvironmentNotFound",
  "message": "Readable error description",
  "target": "ApplicationFamily/EnvironmentName",
  "extensionData": {
    "key": "value"
  },
  "clientError": [
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Implementation Recommendations​

  1. Review current error handling in ConnectionClient.Codeunit.al
  2. Parse all error response properties (not just message)
  3. Log error codes for troubleshooting
  4. Display user-friendly messages based on error codes
  5. Handle nested clientError arrays
  6. Special handling for known error scenarios:
    • environmentNameNotValid
    • maximumNumberOfEnvironmentsAllowedReached
    • maximumStorageCapacityUsageReached
    • conflictingDeveloperExtensions

5.2 Operation Polling & Status Monitoring​

Status: ✅ LIKELY IMPLEMENTED
Priority: LOW

API Guidance (v2.9+)​

For async operations (Create, Copy, Delete), consumers should:

  • Poll the operations endpoint to check status
  • NOT poll the environments endpoint for status updates

Current Implementation Check​

Review if polling strategy follows v2.9+ guidance

6. Additional Features & Enhancements​

6.1 Available Applications Discovery​

Status: ❓ UNKNOWN
Priority: LOW

Feature Description​

Discover available application families, countries, rings, and versions before creating environments

API Endpoints​

GET /admin/v2.28/applications
GET /admin/v2.28/applications/{applicationFamily}/Countries/{countryCode}/Rings/{ringName}

Implementation Recommendations​

  1. Create application catalog functionality
  2. Cache available options
  3. Use for validation when creating environments
  4. Show available versions per country/ring

6.2 Time Zone Management​

Status: ⚠️ PARTIALLY IMPLEMENTED
Priority: LOW

API Endpoint​

GET /admin/v2.28/applications/settings/timezones

Current Implementation​

  • Some support exists (mentioned in connection client)
  • Needs verification

Implementation Recommendations​

  1. Fetch and cache available time zones
  2. Provide dropdown selection for update window time zone
  3. Display times in user's local time zone
  4. Show UTC equivalent

6.3 Enhanced Notification Features​

Status: ❓ NEEDS RESEARCH
Priority: LOW

Feature Description​

The API supports administrative notifications. Research needed to determine:

  • What notification types are available
  • How to configure them
  • How to receive them

Implementation Recommendations​

  1. Research notification API endpoints
  2. Add notification preferences to connection settings
  3. Display notifications in Admin Hub
  4. Support webhook/polling for notifications

7. Implementation Priority Matrix​

FeaturePriorityComplexityImpactRecommended Phase
API Version Update to v2.28HIGHLowMediumPhase 1
Environment RecoveryHIGHMediumHighPhase 1
Certificate AuthenticationHIGHHighHighPhase 1
Point-in-Time RestoreHIGHHighHighPhase 2
Storage MonitoringMEDIUMMediumMediumPhase 2
Enhanced Error HandlingMEDIUMMediumMediumPhase 2
App Insights Key ManagementMEDIUMLowLowPhase 3
Security Group ManagementMEDIUMMediumMediumPhase 3
Power Platform IntegrationMEDIUMMediumLowPhase 3
AppSource Update CadenceLOWLowLowPhase 4
Version Lifecycle TrackingLOWLowMediumPhase 4
Application DiscoveryLOWLowLowPhase 4

8. Implementation Phases​

Phase 1: Critical Updates & Security (Q1 2026)​

  1. Update API version to v2.28
  2. Implement certificate-based authentication
  3. Add environment recovery capabilities
  4. Improve error handling

Estimated Effort: 3-4 weeks

Phase 2: Data Protection & Monitoring (Q2 2026)​

  1. Implement point-in-time restore
  2. Add storage monitoring and alerts
  3. Enhanced operation tracking
  4. Delegated admin support (if needed)

Estimated Effort: 4-6 weeks

Phase 3: Management Features (Q3 2026)​

  1. Power Platform integration
  2. Application Insights management
  3. Security group configuration
  4. M365 license settings

Estimated Effort: 3-4 weeks

Phase 4: Quality of Life (Q4 2026)​

  1. Version lifecycle tracking
  2. AppSource update cadence
  3. Application discovery
  4. Time zone enhancements
  5. Notification system

Estimated Effort: 2-3 weeks

Official Documentation​

Authentication & Security​

Admin Center UI​

10. Appendix: API Version History​

Key Versions & Features​

VersionReleasedKey Features
v2.282025-11Latest available version
v2.26Unknown64-bit storage support for large databases
v2.21UnknownCurrent version used by Admin Hub, Power Platform integration
v2.18UnknownSoft delete & recovery
v2.17UnknownEnhanced operation types
v2.12UnknownM365 license access settings
v2.11UnknownEnhanced modify operations
v2.10UnknownRestart operations
v2.9UnknownAsync operations, improved polling guidance
v2.8UnknownDelete operations
v2.7UnknownOperations on all environments
v2.6UnknownApp operations tracking
v2.4UnknownPoint-in-time restore
v2.3UnknownEnvironment rename

11. Next Steps​

  1. Review & Prioritize: Review this document with the development team and prioritize features
  2. Technical Design: Create detailed technical design for Phase 1 features
  3. Prototype: Build proof-of-concept for environment recovery and certificate auth
  4. Update API Version: Quick win - update to v2.28 and test
  5. Documentation: Update user documentation with new capabilities
  6. Testing Strategy: Define testing approach for new features
  7. Rollout Plan: Plan gradual rollout to customers

Document Information​

Author: GitHub Copilot
Date: December 4, 2025
Version: 1.0
Status: Draft for Review

Review Required By:

  • Technical Architect
  • Product Owner
  • Security Team
  • Development Team Lead

This document is based on Microsoft's official API documentation as of December 2025. API capabilities and recommendations are subject to change. Always verify against the latest official documentation.