How to enable the Work IQ API with Azure usage-based billing

I enabled the Work IQ API in a new tenant so that an agent could work with Microsoft 365 email, meetings, chats, files, and other data.

Because the tenant did not have Microsoft 365 Copilot licenses, I used usage-based billing for Copilot Credits with an Azure subscription as the billing account. During setup, I encountered Microsoft Entra ID error AADSTS650052, which occurs when a service requested by an app has not been enabled or provisioned in the tenant. I also ran into an authentication failure even though validation by the official scripts had passed.

This article breaks down the configuration I used into discrete tasks. I have replaced environment-specific details, including the tenant ID, User Principal Name (UPN), and Azure subscription name, with placeholders.

Table of Contents

• Key takeaways
• Review the architecture and prerequisites
• Check the required Microsoft Entra roles
• Set up PowerShell and the Work IQ CLI
• Create the Work IQ service principal
• Grant admin consent for the Work IQ CLI
• Enable Azure usage-based billing
• Verify the setup with the Work IQ CLI
• Troubleshooting
• Post-setup review
• Summary
• Official sources

Key takeaways

The Work IQ API can be used with usage-based Copilot Credits in a tenant that does not have Microsoft 365 Copilot licenses. According to the official documentation as of August 10, 2026, Work IQ API usage is billed based on consumption as Copilot Credits rather than through Microsoft 365 Copilot user licenses.

This setup required five tasks:

1. Enable Azure usage-based billing and a spending policy for the Work IQ API
2. Create the Work IQ service principal in the tenant
3. Create the Work IQ CLI and related Work IQ Tools in the tenant
4. Grant tenant-wide admin consent to the delegated permissions requested by the Work IQ CLI
5. Sign in as the user and send a query through the Work IQ CLI

The most important detail is that Work IQ Tools and Work IQ are separate enterprise applications. As of August 10, 2026, Enable-WorkIQToolsForTenant.ps1 in the official repository does not create the Work IQ service principal, and Verify-WorkIQTenant.ps1 does not verify its existence. If validation succeeds but you still receive AADSTS650052, check for the Work IQ service principal separately.

Review the architecture and prerequisites

I used the following environment for this validation.

Work IQ API requests run in the context of the signed-in user. Application-only authentication is not supported. Existing Microsoft 365 permissions, sensitivity labels, and compliance policies continue to apply.

Understand the licensing and billing paths

Work IQ and Microsoft 365 Copilot have different requirements depending on the experience being used.

There is no dedicated per-user SKU to purchase for the Work IQ API. To use the Work IQ API from a CLI as described here, connect an Azure subscription and resource group as the billing destination in the Microsoft 365 admin center, then configure a Copilot Credits usage policy.

Copilot Credits pricing, covered services, and Microsoft 365 base license requirements may change. Before a production rollout, review the official Copilot Credits documentation and your contract terms.

Check the required Microsoft Entra roles

This work requires Microsoft Entra directory roles, not Azure RBAC roles. Being an Owner or Contributor on the Azure subscription alone does not allow you to create service principals in Microsoft Entra or grant tenant-wide admin consent.

These administrative roles do not need to remain assigned. If your organization uses Microsoft Entra Privileged Identity Management (PIM), activate the required roles only for the duration of the work and deactivate them afterward.

Admin consent grants an app broad access to organizational data. Before approving it, verify the publisher, application ID, and requested permissions shown on the consent screen.

Set up PowerShell and the Work IQ CLI

On macOS, I installed PowerShell through Homebrew.

brew install powershell
pwsh --version

Next, clone the official Work IQ repository.

git clone --depth 1 https://github.com/microsoft/work-iq.git
cd work-iq

Use the official scripts to configure the service principals and permission grants for Work IQ Tools, the Work IQ CLI, and the related MCP server. If the Microsoft Graph PowerShell module is not installed, the script installs it for the CurrentUser scope.

pwsh -NoProfile -File ./scripts/Enable-WorkIQToolsForTenant.ps1
pwsh -NoProfile -File ./scripts/Verify-WorkIQTenant.ps1

When the browser opens, sign in with an administrative account for the tenant you are configuring. If the account belongs to multiple tenants, confirm that you are signing in to the intended tenant.

Create the Work IQ service principal

The official Work IQ enablement procedure instructs you to create, once per tenant, a service principal for the Microsoft first-party application with this application ID:

fdcc1f02-fc51-4226-8753-f668596af7f7

This value is the Work IQ application ID published by Microsoft. It is not a tenant ID or client secret.

To create the service principal with Microsoft Graph PowerShell, run these commands:

Connect-MgGraph `
  -TenantId "<TENANT_ID>" `
  -Scopes "Application.ReadWrite.All"

New-MgServicePrincipal `
  -AppId "fdcc1f02-fc51-4226-8753-f668596af7f7"

After creating it, search by application ID to confirm that it exists.

Get-MgServicePrincipal `
  -Filter "appId eq 'fdcc1f02-fc51-4226-8753-f668596af7f7'" |
  Select-Object DisplayName, AppId, Id

If you use the Azure CLI, you can also create it with the command provided in the official procedure.

az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7

Grant admin consent for the Work IQ CLI

The Work IQ CLI has the following application ID:

ba081686-5d24-4bc6-a0d6-d034ecffed87

The PowerShell script in the official repository grants admin consent to the Microsoft Graph delegated permissions required by the Work IQ CLI and the related permissions required by Work IQ Tools.

The user must also start the consent flow from the Work IQ CLI. In CLI version 1.0.0.28144, which I tested, specify the target tenant’s UPN with --account instead of specifying the tenant ID with --tenant-id.

npx -y @microsoft/workiq@latest \
  --account <USER_UPN> \
  auth consent

Sign in through the browser, verify the target tenant and requested permissions, and provide consent. Continue after the CLI reports that consent succeeded.

Enable Azure usage-based billing

As of August 10, 2026, usage-based billing for the Work IQ API is configured from Cost management in the Microsoft 365 admin center.

Follow these steps:

1. In the Microsoft 365 admin center, open Copilot, then Cost management
2. Start the usage-based billing configuration
3. Connect the Azure subscription and resource group to use for billing
4. Include Work IQ API in the covered services
5. Assign the users or groups that will use the service to the spending policy
6. Set monthly credit limits for the organization and each user, and configure alerts if needed
7. Activate the spending policy

For this proof of concept (PoC), I set the organization’s monthly limit to 200 Copilot Credits and each user’s monthly limit to 100 Copilot Credits. These values are examples, not recommendations. Set your limits according to the number of users, expected query frequency, and acceptable budget.

The unit configured here is Copilot Credits, not US dollars. The Cost management dashboard shows total consumption, remaining capacity, and usage by user and service.

Confirm that the policy is active, not merely created. If it has not been activated, the CLI may return The caller is not entitled to use this tool. or another message that appears to indicate a missing license.

Verify the setup with the Work IQ CLI

Specify the user’s UPN and send a simple question about their calendar.

npx -y @microsoft/workiq@latest \
  --account <USER_UPN> \
  ask -q "What's on my schedule today?"

In my environment, Work IQ returned a response explaining that there were no events on the specified date. Whether an event existed was not the point of the test. The important result was that Work IQ had checked the Microsoft 365 calendar and returned an answer.

This successful response confirmed at least the following:

• The Work IQ CLI could authenticate as a user in the target tenant
• The CLI could acquire a token for the Work IQ resource
• The required service principals and delegated consent were in place
• The spending policy that included the Work IQ API was active
• The user could access the Microsoft 365 data plane within the scope of their permissions

Do not include actual email subjects, meeting names, participant names, or complete responses in public articles or work logs.

Troubleshooting

AADSTS650052

When I first opened the admin consent URL for the Work IQ CLI, I received an error with the following message:

AADSTS650052: The app is trying to access a service
'fdcc1f02-fc51-4226-8753-f668596af7f7' (Work IQ)
that your organization lacks a service principal for.

The target tenant did not have a service principal for Work IQ. Although Work IQ Tools existed, it was a different application and could not take its place.

As of August 10, 2026, Enable-WorkIQToolsForTenant.ps1 in the official repository does not create Work IQ, and Verify-WorkIQTenant.ps1 does not check for it. This behavior is reported in microsoft/work-iq#172.

Even if Verify-WorkIQTenant.ps1 reports the following success message, check separately for application ID fdcc1f02-fc51-4226-8753-f668596af7f7.

All checks passed. Work IQ is fully provisioned in this tenant.

A missing-license message

After I configured the service principal and consent, the CLI returned a message indicating that no valid license was available.

In this case, the problem was not the lack of a Microsoft 365 Copilot license. The usage-based billing policy that included the Work IQ API had not been activated. The query succeeded with the same CLI version after I activated the spending policy and assigned the target user.

A similar issue is reported in microsoft/work-iq#148. Because settings may take time to propagate, confirm the policy, user assignment, inclusion of the Work IQ API, and active status, then wait before trying again.

--tenant-id is not recognized

CLI version 1.0.0.28144 did not support these options:

--tenant-id
-t

Instead, specify the UPN for the target tenant with --account <USER_UPN>. CLI options may vary by version, so check --help in your environment as well.

ask: command not found

ask is a Work IQ CLI subcommand, not a standalone zsh command. Run the complete command beginning with npx, as shown here:

npx -y @microsoft/workiq@latest \
  --account <USER_UPN> \
  ask -q "What's on my schedule today?"

Post-setup review

After verifying the setup, deactivate any Microsoft Entra roles that you enabled temporarily. Do not leave a PoC available to every user without first reviewing these settings against your operational requirements:

• Whether to require user assignment for the Work IQ CLI enterprise application
• Whether to limit the spending policy to only the users or groups that need it
• Whether the organization-level and user-level credit limits and alerts are appropriate
• Whether to require MFA or a compliant device through Conditional Access
• Whether Purview auditing, DLP, and sensitivity labels apply as expected
• Whether to review enterprise application consent and assignments regularly

Work IQ handles email, meeting transcripts, Teams messages, SharePoint and OneDrive documents, and other data available to the user. Even in a PoC, use the same data boundaries, least-privilege approach, and cost limits that you would apply in production.

Summary

I was able to use the Work IQ API with Azure usage-based Copilot Credits in a tenant without Microsoft 365 Copilot licenses.

The essential steps are to create the Work IQ service principal as a one-time setup, grant delegated consent for the Work IQ CLI and Work IQ Tools, and activate a spending policy that includes the Work IQ API.

If you receive AADSTS650052, do not rely only on the PowerShell script’s success message. Confirm that the service principal for the application ID shown in the error exists in the target tenant. If a message appears to indicate a missing license, check the Copilot Credits policy and target user assignment in addition to the presence or absence of a Microsoft 365 Copilot SKU.

Official sources

• Microsoft Work IQ API
• Enable your tenant for Work IQ
• Usage-Based Billing and Cost Management for Copilot Credits
• Grant tenant-wide admin consent to an application
• Microsoft Work IQ CLI repository
• Enable/Verify tenant scripts omit the Work IQ app #172
• WorkIQ CLI returns 403 Forbidden / caller not entitled #148