Managing Copilot Credits with Environment-Level Allocation

1. The Copilot credit model

Copilot capabilities in Power Platform — Copilot Studio messages, agent actions, generative answers and related AI features — are metered in Copilot Credits. Credits are purchased at the tenant level and land in a shared tenant capacity pool.

Without governance, any environment can consume from that shared pool. One busy test environment or a runaway agent can therefore burn credits that a production workload depends on. Environment-level allocation is the control that fixes this: it lets an administrator reserve a fixed number of credits for an environment and decide whether that environment may reach past its reservation into the tenant pool.

2. Setting it in the Power Platform admin center

The manual path an administrator would normally take:

1. Sign in to the Power Platform admin center as a Power Platform or Global Administrator.
2. Open Licensing (or Capacity) and select the Copilot Credits currency summary.
3. Choose Manage capacity, or select the target environment from the allocation list.
4. Enter the number of credits to allocate to that environment.
5. Set the capacity-overage behaviour — the “Draw from the available capacity in my tenant” toggle.
6. Save, and repeat the whole sequence for every remaining environment.

That last step is the problem. The portal is fine for one environment, but the workflow is manual, click-heavy, easy to get wrong, hard to review, and has no repeatability across dozens or hundreds of environments.

3. What each setting actually controls

Behind the portal UI, every environment allocation is made up of three values.

Enforcement rule types

The TenantPool toggle

The TenantPool rule is the direct equivalent of the portal's “Draw from the available capacity in my tenant” switch.

4. Allocation value rules

The API accepts only certain allocation values:

• 0 — allocate no environment-specific credits.
• Any value greater than or equal to 500, for example 500, 1000, 2500.

5. Why do this programmatically

6. The underlying API

The scripts call the Microsoft Power Platform Licensing REST API directly.

Read current allocations

GET https://api.powerplatform.com/licensing/allocationsByEnvironment/{environmentId}?api-version=2024-10-01

Update allocations

PATCH https://api.powerplatform.com/licensing/allocationsByEnvironment?api-version=2024-10-01

Request body

{
  "environmentId": "00000000-0000-0000-0000-000000000000",
  "currencyAllocations": [
    {
      "currencyType": "MCSMessages",
      "allocated": 0,
      "enforcementRules": [
        {
          "ruleType": "TenantPool",
          "enabled": false
        }
      ]
    }
  ]
}

Reference: Get Allocations By Environment · Update Allocations By Environment

7. What the scripts do

Execution flow

The client secret is taken as a PowerShell SecureString, converted in memory only at the moment the token is requested, and cleared immediately afterwards — it never appears in a script file, a CSV, or the command line.

8. Updating a single environment

Always preview first with -WhatIf:

$clientSecret = Read-Host "Enter client secret" -AsSecureString

.\Set-PowerPlatformSingleEnvironmentAllocation.ps1 `
    -EnvironmentId "00000000-0000-0000-0000-000000000000" `
    -TenantId      "11111111-1111-1111-1111-111111111111" `
    -ClientId      "22222222-2222-2222-2222-222222222222" `
    -ClientSecret  $clientSecret `
    -CurrencyType  MCSMessages `
    -Allocated     0 `
    -EnforcementRuleType    TenantPool `
    -EnforcementRuleEnabled $false `
    -WhatIf

Review the printed PATCH body. If it is correct, run the same command without -WhatIf to apply it.

9. Updating many environments from CSV

The CSV describes the desired allocation state for the whole estate:

EnvironmentId,Allocated,EnforcementRuleType,EnforcementRuleEnabled
00000000-0000-0000-0000-000000000000,0,TenantPool,false
11111111-1111-1111-1111-111111111111,500,TenantPool,true
22222222-2222-2222-2222-222222222222,1000,Alert,true

The -CurrencyType parameter applies to every row.

$clientSecret = Read-Host "Enter client secret" -AsSecureString

.\Set-PowerPlatformEnvironmentAllocationsFromCsv.ps1 `
    -CsvPath      ".\examples\allocations.example.csv" `
    -TenantId     "11111111-1111-1111-1111-111111111111" `
    -ClientId     "22222222-2222-2222-2222-222222222222" `
    -ClientSecret $clientSecret `
    -CurrencyType MCSMessages `
    -WhatIf

PowerShell prints one What if message per environment. Remove -WhatIf to apply. Because the CSV is a plain text file, it can be committed, diffed and pull-request reviewed like any other configuration — the allocation plan becomes code.

10. Common scenarios

Fence off a non-production environment completely

Stop a sandbox from consuming any Copilot credits, including pooled tenant capacity:

Allocated              = 0
EnforcementRuleType    = TenantPool
EnforcementRuleEnabled = false

Give a project a fixed budget with no overage

Reserve credits, but do not let the environment exceed them:

Allocated              = 1000
EnforcementRuleType    = TenantPool
EnforcementRuleEnabled = false

Reserve credits but allow burst from the pool

Typical production configuration — a guaranteed baseline plus access to spare tenant capacity:

Allocated              = 2500
EnforcementRuleType    = TenantPool
EnforcementRuleEnabled = true

Monitor without blocking

Let the workload continue but raise a notification on overage:

Allocated              = 500
EnforcementRuleType    = Alert
EnforcementRuleEnabled = true

11. Prerequisites

• PowerShell 5.1 or newer.
• A Microsoft Entra app registration with a client secret.
• Power Platform API permission Licensing.Allocations.ReadWrite (or Licensing.Allocations.Read for read-only), with admin consent granted.
• The service principal registered as a Power Platform management application via New-PowerAppManagementApp.
• Power Platform administrative access in the tenant.

The Power Platform API application ID is 8578e004-a5c6-46e7-913e-12f58912df43. Full step-by-step setup instructions are in the repository README.

12. Safety and troubleshooting

Before every production run

• Run with -WhatIf and read the PATCH body.
• Review the CSV contents and confirm each environment ID.
• Confirm the tenant has enough remaining capacity for the requested allocations.
• Test the enforcement-rule change in a non-production environment first.

Common errors