Skip to content

Agent Costs Billing Connection

Sam Betts edited this page Nov 4, 2026 · 2 revisions

Agent Costs → Agent Costs Billing Connection

Connect a billing administrator

Released billing connection page with local synthetic status and consent guidance

The capture illustrates the released UI, not a completed consent flow, stored credential or retrieved consumption.

How it works. Microsoft restricted the tenant-wide per-agent consumption route to its own clients (Power CAT issue), and it refuses the runtime app's app-only identity on every consumption route. So:

  • Consumption needs a connected billing administrator (this section). The importer reads each day's per-person consumption, then each active person's per-agent consumption, and adds those up per agent. The per-agent "people" figure is the number of distinct people contributing.
  • Capacity works app-only and is imported with or without a connection. With no connection the importer makes no consumption calls and the portal shows an informational "connection required" message, not an error.
  • Caveat: per-agent figures cover only consumption Microsoft attributes to a person. Anything it does not attribute to a user is not visible through any permitted API; the capacity tile's tenant total remains authoritative.
  • API volume: one daily user-list read plus paging, then at least one resource read per active user-day. The default seven-day window is roughly 70,000 resource calls for 10,000 daily active users, or 1.4 million if all 200,000 users were active every day, before extra pages and retries. These are synthetic planning examples, not tenant measurements. Concurrency is bounded at six; each paginated read has a 500-page safety ceiling. This is a bound on concurrency/paging, not a 500-call tenant budget. Keep the normal 24-hour cadence, start with the smallest useful trailing window, and monitor cycle completion and throttling before expanding. Raising the trailing window (maximum 180 days), or setting the interval to zero, multiplies the API load.
  • Per-agent figures are tenant-wide; per-person rows follow your user-group filter.

UserGroupsFilter narrows stored per-person rows, not these tenant-wide billing reads: it is not an API-volume control for this import. This differs from the scoped prompt-history import.

Connecting requires Administration → Copilot Studio billing connection:

  1. Open Microsoft Entra ID → App registrations → your runtime app → Authentication → Add a platform → Web (or add a URI to its existing Web platform). Register https://<portal-host>/signin-agent-costs. The callback is the configured WebAppURL, without its trailing slash, plus /signin-agent-costs. Register a separate callback for each hosted slot or local instance you use. For a synthetic local example with WebAppURL=https://localhost:44400/, add https://localhost:44400/signin-agent-costs. Copy the actual local callback from the error/request rather than copying this example's port. Keep the existing portal and Teams callbacks. This is a Web callback, not SPA or mobile/desktop. Do not include a hash route, query string or trailing slash after signin-agent-costs.
  2. Open API permissions → Add a permission → APIs my organization uses and search by the public application ID 8578e004-a5c6-46e7-913e-12f58912df43 (Power Platform API). Select Delegated permissions, add CopilotStudio.Licenses.Read (Read Copilot Studio Licenses) and EnvironmentManagement.Environments.Read (Read Environments), then select Grant admin consent for your organization and confirm their granted status. These are read-only delegated permissions advertised by that API; do not choose application permissions or a similarly named legacy resource. If a permission is unavailable in your tenant, consult Microsoft rather than substituting a write permission. The flow requests https://api.powerplatform.com/.default and openid profile offline_access: .default uses the configured delegated permissions; it is not itself a permission to add. The entitlement reference does not document a Licensing.Read scope. The connection's consumption probe checks actual billing access; configuring a resource does not guarantee that access. See Microsoft's authentication setup and the endpoint reference.
  3. Configure the existing Storage connection string and Table service access for both portal and importer. The runtime identity needs Storage Table Data Contributor when using Entra authentication.
  4. Sign in to the portal with Portal.Administration and Power Platform Administrator or equivalent billing access. Open Administration > Copilot Studio billing connection and click Connect or reconnect an administrator, signing in with the same account. Before saving, the portal checks that Microsoft lets the account read Copilot Studio usage. A failed attempt leaves any previous connection in place.
  5. Make sure Copilot Studio credits is switched on in the installer. After a new connection, usage is imported at the next scheduled importer run - you don't have to wait until the next day.

The deployment shares one connection, not one per reader. Its MSAL token cache is encrypted and authenticated in AnalyticsState / AgentCostDelegatedAuth, using the runtime secret or certificate. Tokens never appear on the status page or in its API responses. There is no SQL/config-schema change, no browser-only connection and no in-memory credential fallback when Storage is absent or unavailable.

Reconnect needed means renewal or delegated billing access was refused: check account access, consent, refresh expiry/revocation and Conditional Access, then reconnect. Transient token/Storage failures preserve the connection. Changing the runtime encryption credential can require reconnection. An endpoint-specific refusal is reported on the Agent Costs page and asks for a reconnect. The flow does not bypass policies that require another interactive sign-in.

Disconnect stops consumption imports (the portal shows "connection required"); it does not revoke Entra consent, remove imported figures or cancel an already-running import. Azure Cost Management and the Copilot Studio capacity read remain app-only throughout.

State addresses are stable: Connection holds the current generation; Cache_<generation> and Error_<generation> belong to it and expire 90 days after their last write. An old refresh cannot replace the active generation after disconnect/reconnect. Restrict the partition and its backups as credentials. In ImportSchedule, connected/previously-connected deployments use CopilotStudioCreditsLastImported_<generation>; the original CopilotStudioCreditsLastImported key remains for deployments with no connection history. AzureCostLastImported is unchanged. Clear the matching current credit stamp to force a retry.

This requires upgrading to a build with the connection page and configuring/authorizing it afterwards. Synthetic tests validate the flow; access for a particular deployment still needs its own administrator's successful connection and subsequent importer run.

Connection setup troubleshooting

Error / symptom Meaning Action
AADSTS650057: Invalid resource for https://api.powerplatform.com The runtime app has not configured that API as a requested resource. The service principal's Power Platform Reader role is a separate grant. Add the delegated permissions and grant admin consent in step 2, then start a fresh Connect attempt.
AADSTS50011: redirect URI does not match The callback sent by this instance is not registered on the runtime app. A hosted callback does not configure a local development callback. Add the exact URI shown in the error under Authentication → Web. Check scheme, host, local port, path and configured WebAppURL; retain the other callbacks. If a hosted instance sends localhost, correct that instance's WebAppURL instead of authorizing localhost for it. Retry Connect.
Consent required / administrator approval required The API permissions exist but the required consent has not been granted. Have an authorized Entra administrator grant consent; reconnect after the change.
Account mismatch / access refused The selected billing account differs from the portal administrator, lacks portal Administration or cannot read consumption. Sign in and connect with the same authorized account; check its Power Platform billing access.
The account signed in, but Microsoft wouldn't let it read Copilot Studio usage The verification request (the per-person /users read) returned 401/403. Check consent on the delegated permissions, the account's Power Platform billing access and Conditional Access; do not grant write/admin roles. The previous connection is preserved.
Storage unavailable / reconnect needed Durable credential storage or token renewal failed. Check the shared Storage/Table access, runtime encryption credential, consent and Conditional Access. Do not paste tokens into app settings or bypass policy.

After connecting, refresh the connection status and confirm the next credit import succeeds on the Health / Agent Costs pages. A successful Entra sign-in alone does not prove billing API access or a completed import. Neither new callback registration nor delegated permission consent needs a new SQL migration. Entra registration changes alone do not require redeploying the application.

Option A — assign a Power Platform role (least privilege, try first)

You need the Enterprise Application Object ID of the runtime app — not its Application (client) ID. These are different GUIDs and using the wrong one is the most common mistake here.

Find it in Microsoft Entra ID → Enterprise applications → [your runtime app] → Object ID. The Object ID under App registrations is a different value and will not work.

Sign in as a Power Platform Administrator (or Power Platform role-based access control administrator) and run:

Install-Module -Name Az.Accounts     # if you don't already have it

$TenantId              = "<your tenant id>"
$EnterpriseAppObjectId = "<runtime app's ENTERPRISE APPLICATION object id>"

Connect-AzAccount -TenantId $TenantId
$secure = (Get-AzAccessToken -TenantId $TenantId -ResourceUrl "https://api.powerplatform.com/").Token
$token  = [System.Net.NetworkCredential]::new("", $secure).Password

$headers = @{ Authorization = "Bearer $token"; 'Content-Type' = 'application/json' }

$body = @{
    roleDefinitionId  = "c886ad2e-27f7-4874-8381-5849b8d8a090"   # Power Platform reader
    principalObjectId = $EnterpriseAppObjectId
    principalType     = "ApplicationUser"
    scope             = "/tenants/$TenantId"
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
    -Uri "https://api.powerplatform.com/authorization/roleAssignments?api-version=2024-10-01" `
    -Headers $headers -Body $body

Use Power Platform reader. This import only reads. The built-in roles are:

Role Role ID Use for this?
Power Platform reader c886ad2e-27f7-4874-8381-5849b8d8a090 ✅ Yes — least privilege
Power Platform contributor ff954d61-a89a-4fbe-ace9-01c367b89f87 No — grants write
Power Platform owner 0cb07c69-1631-4725-ab35-e59e001c51ea No
Power Platform RBAC administrator 95e94555-018c-447b-8691-bdac8e12211e No

These are Microsoft-published built-in role definition IDs, not tenant-specific application or role-assignment IDs. Keep the reader role ID as written; substitute only your own tenant and enterprise application object IDs.

Verify it took:

(Invoke-RestMethod -Method Get `
    -Uri "https://api.powerplatform.com/authorization/roleAssignments?api-version=2024-10-01" `
    -Headers $headers).value |
  Where-Object { $_.principalObjectId -eq $EnterpriseAppObjectId } |
  Format-Table roleDefinitionId, scope, principalType

⚠️ Power Platform RBAC role assignment is a preview feature at the time of writing. If your tenant does not offer it, use Option B.

Option B — register as an admin application (legacy)

The older mechanism, still supported, and the one the "Caller is not an authorized app" message historically refers to:

Install-Module -Name Microsoft.PowerApps.Administration.PowerShell

Add-PowerAppsAccount                                   # sign in as a Power Platform admin
New-PowerAppManagementApp -ApplicationId "<runtime app's APPLICATION (CLIENT) ID>"

Note this one takes the Application (client) ID, not the Enterprise Application Object ID — the opposite of Option A.

This grants the service principal tenant-wide Power Platform administrative access, which is considerably broader than Power Platform reader. It is historical context, not a recommended remedy for an already verified Reader assignment whose consumption requests are refused. Prefer the delegated connection above where an administrator can read those same routes.

Historically, "Caller is not an authorized app" is the message this registration mechanism produces when it is missing. The text alone cannot distinguish that from endpoint-specific access refusal: keep request/correlation evidence privately for Microsoft support rather than broadening privileges blindly.

Then

Check dbo.agent_cost_import_log after the next due Office365ActivityImporter run. A successful connection/disconnect permits a retry on the next cycle. App-only role changes alone do not clear a previous daily refusal stamp; clear the matching ImportSchedule key described above to force a retry.


Return to Agent Costs · All topics in this guide

Previous: Agent Costs Power Platform Access · Next: Agent Costs Import Configuration

Start here

Copilot analytics

Using the portal

Install & configure

Beyond Copilot

Operate

Upgrading from an older build

Reference

Project

Clone this wiki locally