Repository navigation
Agent Costs Billing Connection
Agent Costs → Agent Costs Billing Connection

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:
- 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 withWebAppURL=https://localhost:44400/, addhttps://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 aftersignin-agent-costs. - 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 requestshttps://api.powerplatform.com/.defaultandopenid profile offline_access:.defaultuses the configured delegated permissions; it is not itself a permission to add. The entitlement reference does not document aLicensing.Readscope. 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. - Configure the existing
Storageconnection string and Table service access for both portal and importer. The runtime identity needs Storage Table Data Contributor when using Entra authentication. - 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.
- 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.
| 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.
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 $bodyUse 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.
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.
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
- Copilot analytics overview
- Copilot Adoption user guide
- Copilot Adoption setup (admins)
- Work Trend Index
- Copilot investment
- Copilot spend
- Agent costs
- Prompt categories
- Copilot credit history (preview)
- Agent 365 package catalog
- The Copilot data in depth
- Prerequisites
- App registrations setup
- Install with the installer
- Verify the deployment
- Security & permissions model
- Private endpoints (optional)
- Certificate authentication (optional)
- Manual installation
- Activity & usage analytics (Power BI)
- SharePoint page tracking