{"title":"Business Central admin center API - environment settings","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/administration-center-api_environment_settings/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api_environment_settings, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api_environment_settings","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Configure Business Central environment settings via Admin Center API, including update windows, App Insights, security groups, and access controls.","date":"2026-11-18","meta":{"topic":"reference"},"outline":[{"level":1,"title":"Business Central admin center API - environment settings","slug":"business-central-admin-center-api---environment-settings","at":0,"chars":18837},{"level":2,"title":"Get update settings","slug":"get-update-settings","at":160,"chars":1907},{"level":3,"title":"Route parameters","slug":"route-parameters","at":349,"chars":269},{"level":3,"title":"Response","slug":"response","at":618,"chars":1312},{"level":3,"title":"Expected error codes","slug":"expected-error-codes","at":1930,"chars":137},{"level":2,"title":"Get time zones for update settings","slug":"get-time-zones-for-update-settings","at":2067,"chars":1256},{"level":3,"title":"Route parameters","slug":"route-parameters-1","at":2472,"chars":110},{"level":3,"title":"Response","slug":"response-1","at":2582,"chars":741},{"level":2,"title":"Set update settings","slug":"set-update-settings","at":3323,"chars":3083},{"level":3,"title":"Route parameters","slug":"route-parameters-2","at":3538,"chars":269},{"level":3,"title":"Body","slug":"body","at":3807,"chars":1665},{"level":3,"title":"Response","slug":"response-2","at":5472,"chars":294},{"level":3,"title":"Expected error codes","slug":"expected-error-codes-1","at":5766,"chars":640},{"level":2,"title":"Set Application Insights key","slug":"set-application-insights-key","at":6406,"chars":1236},{"level":3,"title":"Route parameters","slug":"route-parameters-3","at":7019,"chars":262},{"level":3,"title":"Body","slug":"body-1","at":7281,"chars":93},{"level":3,"title":"Expected error codes","slug":"expected-error-codes-2","at":7374,"chars":268},{"level":2,"title":"Get security group","slug":"get-security-group","at":7642,"chars":886},{"level":3,"title":"Route parameters","slug":"route-parameters-4","at":7893,"chars":262},{"level":3,"title":"Response","slug":"response-3","at":8155,"chars":373},{"level":2,"title":"Set security group","slug":"set-security-group","at":8528,"chars":751},{"level":3,"title":"Route parameters","slug":"route-parameters-5","at":8793,"chars":262},{"level":3,"title":"Body","slug":"body-2","at":9055,"chars":127},{"level":3,"title":"Response","slug":"response-4","at":9182,"chars":97},{"level":2,"title":"Clear security group","slug":"clear-security-group","at":9279,"chars":526},{"level":3,"title":"Route parameters","slug":"route-parameters-6","at":9543,"chars":262},{"level":2,"title":"Get partner access settings","slug":"get-partner-access-settings","at":9805,"chars":1020},{"level":3,"title":"Route parameters","slug":"route-parameters-7","at":10370,"chars":262},{"level":3,"title":"Response","slug":"response-5","at":10632,"chars":193},{"level":2,"title":"Set partner access settings","slug":"set-partner-access-settings","at":10825,"chars":1089},{"level":3,"title":"Route parameters","slug":"route-parameters-8","at":11463,"chars":262},{"level":3,"title":"Body","slug":"body-3","at":11725,"chars":189},{"level":2,"title":"Get access with Microsoft 365 licenses","slug":"get-access-with-microsoft-365-licenses","at":11914,"chars":759},{"level":3,"title":"Route parameters","slug":"route-parameters-9","at":12358,"chars":262},{"level":3,"title":"Response","slug":"response-6","at":12620,"chars":53},{"level":2,"title":"Set access with Microsoft 365 licenses","slug":"set-access-with-microsoft-365-licenses","at":12673,"chars":796},{"level":3,"title":"Route parameters","slug":"route-parameters-10","at":13123,"chars":262},{"level":3,"title":"Body","slug":"body-4","at":13385,"chars":44},{"level":3,"title":"Response","slug":"response-7","at":13429,"chars":40},{"level":2,"title":"Set app update cadence for environment","slug":"set-app-update-cadence-for-environment","at":13469,"chars":828},{"level":3,"title":"Route parameters","slug":"route-parameters-11","at":13866,"chars":262},{"level":3,"title":"Body","slug":"body-5","at":14128,"chars":129},{"level":3,"title":"Response","slug":"response-8","at":14257,"chars":40},{"level":2,"title":"Get sandbox environment database configuration match eligibility","slug":"get-sandbox-environment-database-configuration-match-eligibility","at":14297,"chars":1817},{"level":3,"title":"Route parameters","slug":"route-parameters-12","at":14904,"chars":262},{"level":3,"title":"Response","slug":"response-9","at":15166,"chars":811},{"level":3,"title":"Expected error codes","slug":"expected-error-codes-3","at":15977,"chars":137},{"level":2,"title":"Match sandbox environment database configuration to production","slug":"match-sandbox-environment-database-configuration-to-production","at":16114,"chars":2507},{"level":3,"title":"Route parameters","slug":"route-parameters-13","at":16459,"chars":262},{"level":3,"title":"Response","slug":"response-10","at":16721,"chars":878},{"level":3,"title":"Expected error codes","slug":"expected-error-codes-4","at":17599,"chars":1022},{"level":2,"title":"Related information","slug":"related-information","at":18621,"chars":216}],"text":"# Business Central admin center API - environment settings\nAllows you to manage environment-specific settings such as the AppInsights key or the update window.\n## Get update settings\nReturns the update settings for the environment.\n```http\nGET /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/upgrade\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application as is. (For example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Response\nReturns the environment's update settings, or \"null\" if none exist\n```json\n{\n  \"preferredStartTime\": string, // Start of environment update window in 24h format (HH:mm). Supported by API version 2.13 and later only.\n  \"preferredEndTime\": string, // End of environment update window in 24h format (HH:mm). Supported by API version 2.13 and later only.\n  \"timeZoneId\": string, // Windows time zone identifier. Supported by API version 2.13 and later only.\n  \"preferredStartTimeUtc\": datetime, // Start of an environment's update window, expressed as an UTC timestamp\n  \"preferredEndTimeUtc\": datetime // End of an environment's update window, expressed as an UTC timestamp\n}\n```\n> NOTE\n> The UTC values identify the current or next immediate occurrence of the update window. For instance, when the request is issued, if the current time is within the update window defined for the environment, then preferredStartTimeUtc will identify an instant in the past, and preferredEndTimeUtc will identify an instant in the future. Otherwise, both the start and end times will identify instants in the future. For a static, deterministic set of values that uniquely identify the definition of the update window for a given environment, refer to the preferredStartTime, preferredEndTime, and timeZoneId values.\n### Expected error codes\nenvironmentNotFound - the targeted environment couldn't be found\n target: {applicationFamily}/{environmentName}\n## Get time zones for update settings\nINTRODUCED IN: API version 2.13\nReturns a list of time zones and basic information associated with them, such as daylight saving time and the current offset from Coordinated Universal Time (UTC). Time zone identifiers are the only allowed values for the timeZoneId parameter of the update settings.\n```http\nGET /admin/{apiVersion}/applications/settings/timezones\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\n### Response\nReturns a wrapped array of time zones.\n```json\n{\n  \"value\":\n    [\n      {\n        \"id\": string, // Time zone identifier (For example, \"Romance Standard Time\")\n        \"displayName\": string, // Display name of the time zone (for example, \"(UTC+01:00) Brussels, Copenhagen, Madrid, Paris\")\n        \"currentUtcOffset\": string, // Offset from UTC, expressed as a time span with +/-HH:mm format (for example, \"+01:00\", \"-09:00\")\n        \"supportsDaylightSavingTime\": boolean, // Indicates whether the time zone supports daylight saving time rules\n        \"isCurrentlyDaylightSavingTime\": boolean // Indicates whether daylight saving time is in effect for the given time zone, at the instant the request is issued\n      }\n    ]\n}\n```\n## Set update settings\nSets the update window start and end times.\n```http\nContent-Type: application/json\nPUT /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/upgrade\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application as is. (For example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Body\nWith API version 2.13 and later, there are two different parameter sets for defining the update window: the wall-time + timezone parameter set and the UTC parameter set. Consumers can provide either parameter set, but not both. Earlier API versions only support the UTC parameter set.\n The wall-time + timezone parameter set identifies the clock time (or \"real time\")&mdash;expressed in 24-hour format, like \"22:00\" for 10:00 PM or \"07:30\" for 7:30 AM&mdash;for a given time zone. The time zone ID must be a valid Windows time zone identifier<https://learn.microsoft.com/windows-hardware/manufacture/desktop/default-time-zones>, for example, \"Romance Standard Time\" or \"Pacific Standard Time\".\n The UTC parameter set identifies the start and end times in Coordinated Universal Time.\n> NOTE\n> If you use the UTC parameter set when modifying the update window settings and the country of the environment supports multiple time zones, the time zone shown on the Environment Details page in the admin center resets to the default time zone for the country. This result might not be desirable. We recommend using the new parameter set when consuming API v2.13 and later.\nExample with wall-time + timezone parameter set (supported only by API v2.13 and later):\n```json\n{\n  \"preferredStartTime\": string, // Start of environment update window,\n  \"preferredEndTime\": string, // End of environment update window\n  \"timeZoneId\": string // Windows time zone identifier\n}\n```\nExample with UTC parameter set:\n```json\n{\n  \"preferredStartTimeUtc\": datetime, // Start of environment update window\n  \"preferredEndTimeUtc\": datetime // End of environment update window\n}\n```\n### Response\nReturns the updated settings\n```json\n{\n  \"preferredStartTimeUtc\": datetime, // Start of environment update window\n  \"preferredEndTimeUtc\": datetime // End of environment update window\n}\n```\n> NOTE\n> The date components of the values are ignored. Only the time components are used.\n### Expected error codes\nenvironmentNotFound - the targeted environment couldn't be found\n target: {applicationFamily}/{environmentName}\n- invalidRange: - the targeted logical range is invalid in some way\n target: \"Preferred Upgrade Window\" - the specified window is too small\nrequestBodyRequired - the request body must be provided\nScheduledUpgradeConstraintViolation - the update window conflicts with the current update date set for the environment. Either the update would occur outside the allowed update date range or, if the update date is today, the update window is in the past. Adjust the update window or change the update date.\n## Set Application Insights key\nSets the connection string or instrumentation key an environment uses for Azure Application Insights resource, which you can use to gather telemetry. See Enable Environment Telemetry<telemetry-enable-application-insights#appinsights>.\n> IMPORTANT\n> This process requires a restart to the environment, which is triggered automatically when you call this API. Plan to do this task during nonworking hours to avoid disruptions.\n```http\nContent-Type: application/json\nPOST /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/appinsightskey\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Body\n```json\n{\n  \"key\": string // The Application Insights key for the environment\n}\n```\n### Expected error codes\nenvironmentNotFound - the targeted environment couldn't be found\n target: {applicationFamily}/{environmentName}\nrequestBodyRequired - the request body must be provided\ncannotSetAppInsightsKey - the targeted environment's status isn't 'Active'\n## Get security group\nINTRODUCED IN: API version 2.8\nGets the Microsoft Entra group currently assigned to an environment.\n```http\nGET /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/securitygroupaccess\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Response\nIf the group exists in Microsoft Graph:\n```json\n{\n    \"id\": \"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb\",\n    \"displayName\": \"Security group 1\"\n}\n```\nIf a previously assigned group no longer exists in Microsoft Graph:\n```json\n{\n    \"id\": \"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb\",\n    \"displayName\": \"\"\n}\n```\nIf no group is configured for the environment, returns 204.\n## Set security group\nINTRODUCED IN: API version 2.8\nAssigns a Microsoft Entra group to an environment.\n```http\nContent-Type: application/json\nPOST /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/securitygroupaccess\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Body\n```json\n{\n  \"Value\": GUID // The object Id of the Microsoft Entra group, \"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb\"\n}\n```\n### Response\nReturns 200 if successful, or 404 if the group doesn't exist in Microsoft Entra ID.\n## Clear security group\nINTRODUCED IN: API version 2.8\nClears a Microsoft Entra group that is currently assigned to an environment.\n```http\nDELETE /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/securitygroupaccess\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n## Get partner access settings\nINTRODUCED IN: API version 2.22\nReturns the partner access status for delegated administrators and foreign multitenant apps, and a list of allowed foreign Microsoft Entra tenant IDs. The status is Disabled, AllowAllPartnerTenants, or AllowSelectedPartnerTenants.\n> IMPORTANT\n> Only internal global administrators can use this API endpoint. Delegated administrator or application authentication isn't supported.\n```http\nGET /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/partneraccess\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Response\n```json\n{\n  \"status\": \"AllowSelectedPartnerTenants\",\n  \"allowedPartnerTenantIds\": [\"aaaabbbb-0000-cccc-1111-dddd2222eeee\"] // Only if status is \"AllowSelectedPartnerTenants\"\n}\n```\n## Set partner access settings\nINTRODUCED IN: API version 2.22\nEnable or disable delegated administrators and foreign multitenant apps to administer and access the environment. Optionally, allowlist only specific foreign Microsoft Entra tenants to administer and access the environment.\nSet status to Disabled, AllowAllPartnerTenants, or AllowSelectedPartnerTenants.\n> IMPORTANT\n> Only internal global administrators can use this API endpoint. Delegated administrator or application authentication isn't supported.\n```http\nPUT /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/partneraccess\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Body\n```json\n{\n  \"status\": \"AllowSelectedPartnerTenants\",\n  \"allowedPartnerTenantIds\": [\"aaaabbbb-0000-cccc-1111-dddd2222eeee\"] // Only if status is \"AllowSelectedPartnerTenants\"\n}\n```\n## Get access with Microsoft 365 licenses\nINTRODUCED IN: API version 2.12\nReturns a boolean value that indicates whether the environment allows access with Microsoft 365 licenses. Supported on environments of version 21.1 or later. See Set Up Access with Microsoft 365 licenses</admin-access-with-m365-license>.\n```http\nGET /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/accesswithm365licenses\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Response\n```json\n{\n  \"enabled\": true/false\n}\n```\n## Set access with Microsoft 365 licenses\nINTRODUCED IN: API version 2.12\nSpecifies whether users can access the environment with Microsoft 365 licenses. Supported on environments of version 21.1 or later. See Set Up Access with Microsoft 365 licenses</admin-access-with-m365-license>.\n```http\nContent-Type: application/json\nPOST /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/accesswithm365licenses\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Body\n```json\n{\n   \"enabled\": true\n}\n```\n### Response\nReturns 200 if successful.\n## Set app update cadence for environment\nSpecifies whether Marketplace apps installed on the environment should be updated with every major environment update or every major and minor update. See tenant-admin-center-manage-apps.\n```http\nContent-Type: application/json\nPUT /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/settings/appSourceAppsUpdateCadence\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Body\n```json\n{\n   \"value\": string //Accepted values are 'Default', 'DuringMajorUpgrade', and 'DuringMajorMinorUpgrade'\n}\n```\n### Response\nReturns 200 if successful.\n## Get sandbox environment database configuration match eligibility\nChecks whether a sandbox environment is eligible to match its database configuration<tenant-admin-center-environments#sandbox-environment-resource-configuration> to that of a typical production environment. Returns the tenant-wide monthly allowance, used/remaining requests, quota reset time, server-defined duration, and a blocked reason when applicable. Does not start an operation or consume quota.\n```http\nGET /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/matchProductionConfiguration/metrics\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Response\nReturns the database configuration match metrics for the current month.\n```\n{\n  \"requestsPerMonth\": int, // Maximum number of requests allowed per calendar month\n  \"requestsUsedThisMonth\": int, // Number of requests used in the current month\n  \"requestsRemainingThisMonth\": int, // Number of requests remaining in the current month\n  \"resetsAtUtc\": datetime, // When the monthly count resets (start of next month, UTC)\n  \"canMatchProductionConfiguration\": bool, // Whether a new request can be made now\n  \"blockedReason\": string, // (enum | \"NotEligible\", \"AlreadyActive\", \"MonthlyLimitReached\", \"QuotaCheckUnavailable\") Why a request can't be made. Null if canMatchProductionConfiguration is true\n  \"durationInHours\": int // How long the production configuration is applied for each request\n}\n```\n### Expected error codes\nenvironmentNotFound - the targeted environment couldn't be found\n target: {applicationFamily}/{environmentName}\n## Match sandbox environment database configuration to production\nRequests temporary (72 hours) database configuration match for a sandbox environment. Independently rechecks eligibility and quota before accepting.\n```http\nPOST /admin/{apiVersion}/applications/{applicationFamily}/environments/{environmentName}/matchProductionConfiguration\n```\n### Route parameters\napiVersion - the version of the Admin Center API. Currently, the latest version is v2.29\napplicationFamily - the family of the environment's application (for example, \"BusinessCentral\")\nenvironmentName - the name of the targeted environment\n### Response\nReturns 202 (Accepted) with details of the operation created to apply the production configuration.\n```\n{\n  \"id\": GUID, // Operation ID\n  \"type\": \"moveToProductionDatabaseConfiguration\",\n  \"status\": \"scheduled\",\n  \"aadTenantId\": GUID,\n  \"createdOn\": datetime,\n  \"startedOn\": datetime,\n  \"completedOn\": datetime,\n  \"createdBy\": string, // Email address if authenticated as user, App ID if authenticated as app\n  \"creatorPrincipalType\": \"user\", // \"user\" or \"application\"\n  \"canceledBy\": string, // Empty for a newly-created operation\n  \"errorMessage\": string,\n  \"parameters\": null, // This operation type has no parameters\n  \"environmentName\": string,\n  \"environmentType\": \"sandbox\",\n  \"productFamily\": string\n}\n```\nWhen the period ends, a moveToSandboxDatabaseConfiguration operation is created automatically to return the environment to its sandbox configuration.\n### Expected error codes\nenvironmentNotFound - the targeted environment couldn't be found\n target: {applicationFamily}/{environmentName}\ninvalidTenantLicense - the Microsoft Entra tenant doesn't have a paid Business Central license\nproductionConfigurationNotEligible - the environment isn't an active sandbox that's eligible for this feature\n target: {applicationFamily}/{environmentName}\nproductionConfigurationAlreadyActive - the production configuration is already applied to the environment\n target: {applicationFamily}/{environmentName}\nproductionConfigurationMonthlyLimitReached - the monthly request limit has been reached\n target: {applicationFamily}/{environmentName}\nproductionConfigurationQuotaCheckUnavailable - the monthly request count couldn't be checked; try again later\n target: {applicationFamily}/{environmentName}\nproductionConfigurationOutcomeUnknown - the request timed out and its outcome is unknown; check the environment's operations before retrying\n target: {applicationFamily}/{environmentName}\n## Related information\nThe Business Central Administration Center API<administration-center-api>\ntenant-admin-center-manage-apps\nMicrosoft Dynamics 365 Business Central Server Administration Tool<administration-tool>"}