Microsoft Work IQ API — Day-1 Hands-On Walkthrough

Microsoft’s Work IQ API goes generally available on 16 June 2026. Ahead of GA, I walked through every part of it on a lab tenant — both halves. The admin half (one URL + one workaround for the famous AADSTS650052 trap). The user half (four install paths to choose from + the EULA). And three real walkthroughs against a synthetic Project Adventure dataset so you can see what good looks like before you build. This post is the plain-English version of what I learned, structured so any team can follow along on their own tenant.

If you’ve been reading the announcement headlines and wondering “is this another Microsoft Graph?” — the short answer is no, it’s a different shape of API. The long answer is the rest of this post.

I also built two tiny working samples you can fork on Day 1 — a morning brief generator (Node script) and an embeddable web-app (Express + browser UI). Both call Work IQ directly via the A2A protocol. Links + full walkthrough later in this post.

Quick Links

• The Translator Analogy — What Work IQ Actually Is
• When to Reach for Work IQ vs Microsoft Graph
• What Microsoft Announced, In 12 Plain Words
• The Four Components of Work IQ
• The 10 Verbs — A Jeweller’s Screwdriver, Not An IKEA Box
• Setup — The Admin Journey (One URL + One Workaround)
• Setup — The User Journey (Pick An Install Path)
• Build Something With It — Two Samples + The Repo
• What It Costs — Copilot Credits Explained
• What Changes When This Lands — Outlook, Scout, Custom Apps
• The Honest Limitations
• Top 5 Errors You’ll Hit (And What To Do)
• Where To Go Next

The Translator Analogy — What Work IQ Actually Is

Imagine you’re a manager in a multilingual company.

Microsoft Graph is the raw transcript service — it hands you every email, calendar event, file, and chat exactly as written. If you want to know who’s the right person to ask about the Q3 deck, you have to read the transcripts yourself, work out who keeps replying to whom, and build a mental picture of who’s actually involved.

Work IQ is the translator who’s been sitting in every meeting for the last two years. You ask “who’s the right person for the Q3 deck?” and you get a person, not a transcript. The translator already understands who collaborates with whom, what Q3 deck means in this tenant, and which meeting was the one where the customer pushed back.

Both layers exist. Both are useful. They do different jobs.

That shape difference is why Microsoft is pitching Work IQ as the recommended foundation for new agent applications on M365 data. Agents are not browser users. They don’t want a paginated list of 500 messages; they want the meaning. Work IQ packages the meaning server-side, before the answer leaves the building.

When to Reach for Work IQ vs Microsoft Graph

The honest follow-up to the translator analogy: “so do I throw Graph away?” No. Pick whichever fits the job in front of you.

The pattern: if your agent runs as a signed-in user reasoning over M365 content, start with Work IQ. If your code runs as a service (batch, background, unattended) or touches non-M365 data, stay on Graph. The two are designed to coexist.

What Microsoft Announced, In 12 Plain Words

Microsoft’s announcement, paraphrased: “a workplace intelligence layer that gives agents a real understanding of everything happening across your business — context, relationships, and patterns — so agents can deliver faster, more accurate, more secure responses than connector-only approaches.”

That’s 30 enterprise words. The 12-word version: “the brain that’s behind Copilot is now its own API for your agents.”

That’s the whole thing. Everything else — the four components, the 10 verbs, the three protocols, the Copilot Credits billing — is implementation detail of that single idea.

Microsoft’s pitch comes with four quantitative claims, all from their own internal testing:

These are Microsoft’s published numbers. I’m planning to measure them directionally on my own tenant — the same question asked via workiq ask versus the equivalent raw-Graph chain, with token counts captured on both sides — and update this post with what I see. The architectural reason the gains are plausible is solid: server-side context packaging beats client-side stitching every time, and that’s exactly what Work IQ does.

The Four Components of Work IQ

Work IQ has four parts. Microsoft sometimes calls them “components”, sometimes “domains”, sometimes “layers” — same thing.

Most early Work IQ integrations will combine Context + Tools. Chat is the heaviest call (it does all the reasoning Copilot would). Workspaces is mostly relevant for larger orgs running long-lived agents — only matters if your agent runs longer than a single request/response.

If you want a one-glance picture of how the four components, three protocols, and your code fit together:

flowchart TD
    A["Your agent code"] --> B["Pick a protocol
A2A · MCP · REST"]
    B --> C["Work IQ"]
    C --> D["Chat
Copilot answer + citations"]
    C --> E["Context
Grounding blocks"]
    C --> F["Tools
10 generic verbs"]
    C --> G["Workspaces
Per-agent scratch"]

You pick a protocol, call one or more of the four components, and Work IQ does the orchestration into Graph or Copilot for you. Your code never has to wire those parts together itself.

The 10 Verbs — A Jeweller’s Screwdriver, Not An IKEA Box

This is the part of Work IQ that took me longest to get my head around — and the part where the design principle pays off.

Microsoft did not ship 100 specific verbs (sendMail, createEvent, getMessages, uploadFile, …). They shipped 10 generic verbs that compose against resource paths. A jeweller’s screwdriver: a small set of bits that fit a huge variety of screws — not the IKEA box where every part has its own dedicated tool.

The 10, organised by category:

The design principle Microsoft repeats every chance they get: fewer tools, more paths. When a new workload ships — say, Loop pages — Microsoft doesn’t add a getLoopPage verb. They add a /me/loopPages resource path. Your agent calls fetch /me/loopPages. The tool surface stays at 10 forever.

Two consequences of this design that matter for builders:

1. Agent prompts get a lot shorter. Instead of teaching the model that sendMail exists, that replyToMessage exists, that forwardMessage exists — you teach it that do_action exists and that it can hit /me/sendMail, /me/messages/{id}/reply, and /me/messages/{id}/forward. The action verbs become resource paths in the prompt, not tools in the registry.
2. Schema discovery is runtime, not bundled. Your agent doesn’t pre-load thousands of OpenAPI type definitions. It calls search_paths to find what’s available, then get_schema on the specific path it wants. This trades a bit of latency for a huge drop in context tokens — which is exactly where Microsoft’s “80% fewer tokens” claim comes from.

A handful of real invocations to make it concrete:

fetch /me/messages                              → read my emails
do_action /me/sendMail                          → send an email
create_entity /me/events                        → create a calendar event
fetch /me/chats/{id}/messages                   → read Teams chat messages
call_function /search/query                     → semantic search across the tenant
ask "What deals closed this quarter?"           → invoke Copilot reasoning
list_agents                                     → discover available agents
get_schema /me/events                           → OpenAPI for the calendar resource

Setup — The Admin Journey (One URL + One Workaround)

This is the part the IT admin does once for the whole tenant. If you’re not the admin, send this section to whoever is — they need 15 minutes.

Before you begin (admin prereqs) — these are the things the section below assumes you have. If any of them are missing, that’s the first thing to fix:

The whole admin journey, end to end:

1. Confirm there are Copilot licences in the tenant
2. Click one URL to grant tenant-wide consent
3. (If needed) run one PowerShell script to unblock a known consent error
4. Confirm in Entra that the Work IQ CLI app is registered

That’s it. Once those four steps are done, every Copilot-licensed user in the tenant can install the CLI and start querying.

Admin Step 1 — Confirm Copilot licences

Work IQ rides on Microsoft 365 Copilot. Open the M365 admin centre → Billing → Licenses. Look for Microsoft 365 Copilot. Any user who’ll invoke Work IQ — or whose context an agent will read on their behalf — needs one assigned.

If you don’t have licences yet, that’s the slowest step in this whole process — there’s a 24-hour propagation lag after you assign them. Plan ahead.

Admin Step 2 — Click the consent URL

Open this URL in your browser, replacing the tenant ID with yours:

https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=ba081686-5d24-4bc6-a0d6-d034ecffed87

Sign in as a Global Admin (or Cloud Application Admin, Application Admin, or Privileged Role Admin), click Accept, and you’ve granted tenant-wide consent for the seven delegated Graph permissions Work IQ uses:

Admin Step 2.5 — The AADSTS650052 trap

Some tenants will see this when clicking the URL above:

AADSTS650052: The app needs access to a service that
your organization has not subscribed to or enabled.

This is not your fault. The Work IQ Tools MCP Server resource (and a few related ones — Mail, Calendar, Teams, OneDrive, SharePoint, Word, Admin, Me, M365 Copilot) doesn’t have a service principal auto-provisioned in your tenant. The consent flow assumes they do and stops.

The fix is one PowerShell script:

# Clone the repo first (or download the scripts/ folder)
git clone https://github.com/microsoft/work-iq.git
cd work-iq

# Optional first — read-only check for what's missing
.\scripts\Verify-WorkIQTenant.ps1

# Then the fix — provisions the missing SPs and grants consent
.\scripts\Enable-WorkIQToolsForTenant.ps1

Before you run it, two things you need to know about the script (it’s well-behaved but does talk to your tenant in a few non-obvious ways):

If you’re on a server / headless box / SSH session where a browser pop won’t work, pass -UseDeviceCode and the script gives you a https://microsoft.com/devicelogin code to enter on any device:

.\scripts\Enable-WorkIQToolsForTenant.ps1 -UseDeviceCode

If your execution policy is Restricted, run with a bypass for the session only:

pwsh -ExecutionPolicy Bypass -File .\scripts\Enable-WorkIQToolsForTenant.ps1

After the script finishes, re-try the consent URL from Admin Step 2 — it’ll go through.

Admin Step 3 — Verify in Entra

After consent, head to Microsoft Entra admin centre → Identity → Applications → Enterprise applications. Filter or search for Work IQ CLI. You should see it listed with admin consent granted (the Permissions tab confirms the 7 Graph scopes). The full set of MCP-server-related SPs (Work IQ Tools, Mail, Calendar, Teams, OneDrive, SharePoint, Word, Admin, Me, M365 Copilot) should also be present in the same list — that’s how you know the Step 2.5 script (if you ran it) did its job.

To view this page you need at least Cloud Application Administrator or Application Administrator (read access). Global Admin works too.

That completes the admin journey. Your users can now install + use Work IQ.

Setup — The User Journey (Pick An Install Path)

Now it’s the user’s turn. Once admin consent is done, every Copilot-licensed user installs Work IQ on their own machine in a few minutes.

Before you begin (user prereqs — the floor below is required no matter which path you pick) —

Each install path below adds its own extras. Pick whichever path matches how you work.

Path A — Copilot CLI plugin (featured — fastest, lowest friction)

If you already use the GitHub Copilot CLI, this is a three-command setup.

Path A prereqs:

Then:

copilot
/plugin marketplace add microsoft/work-iq
/plugin install workiq@work-iq

Restart Copilot CLI (exit then copilot again) and the workiq tool is available inside the same chat surface:

You: What are my upcoming meetings this week?
You: Summarise emails from Sarah about the budget.
You: Find documents I worked on yesterday.

Path B — VS Code one-click install (GUI-driven, no terminal-typing)

If your daily driver is VS Code (or VS Code Insiders) and you’d prefer a button to click rather than commands to type, Microsoft ships a one-click install badge in the GitHub README.

Path B prereqs:

Click the “Install in VS Code” badge in the GitHub README — VS Code opens with an MCP install dialog pre-filled. Click Install, and Work IQ is registered as an MCP server in your VS Code workspace. Copilot Chat in VS Code can then call Work IQ as a tool.

There’s an equivalent badge for VS Code Insiders in the same README.

Path C — Microsoft Scout users (already installed)

If you already use Microsoft Scout (the always-on Autopilot agent Microsoft launched on 2 June 2026), the Work IQ CLI is already bundled in your install.

Path C prereqs:

Try this in a terminal:

workiq --version

If you see something like 0.4.1.19742+d4efecc4df..., you’re set — Scout ships the same binary the standalone install does. You still need to workiq accept-eula once (per account) before first use.

If workiq is not found even after a Scout install, the bundled shim lives at %USERPROFILE%\.copilot\bin\workiq.cmd — open a new terminal (or restart your existing one) so the updated PATH takes effect.

Path D — npm global / npx (universal terminal path)

For anyone outside the Copilot CLI / VS Code / Scout world — or anyone who wants the absolute minimum dependencies — npm is the universal path.

Path D prereqs:

Then:

# Global install (persistent)
npm install -g @microsoft/workiq

# OR on-demand via npx (always pulls the latest, no install)
npx -y @microsoft/workiq mcp

Works on Windows (x64 + ARM64), Linux, macOS, and WSL. The npx form is what most MCP-aware tools (Claude Desktop, Cursor, etc.) use under the hood when you add Work IQ to their JSON config:

{
  "workiq": {
    "command": "npx",
    "args": ["-y", "@microsoft/workiq", "mcp"]
  }
}

Accepting the EULA (one-time, per user)

Whichever path you picked, before your first query you accept the EULA:

workiq accept-eula

This pops a browser for Microsoft sign-in. Use your work account — the one that has the Copilot licence assigned. Once accepted, your token is cached locally and you don’t see this flow again unless you workiq logout or your tenant invalidates the token.

What can go wrong here, and what to do:

Your first query (the moment it clicks)

workiq --account <your-work-email> ask -q "What's on my calendar this week?" --verbose

Replace <your-work-email> with your full UPN — e.g., admin@contoso.onmicrosoft.com or j.smith@yourcompany.com. If you only have one Microsoft account on this machine, you can drop the --account flag and workiq uses the cached one.

What --verbose adds: the conversation ID and request ID. You can later use workiq debug <conversationId> to generate a shareable diagnostic link — useful when you want to compare what an agent saw across runs, or when you raise a support ticket.

Don’t know your tenant domain? Sign in to outlook.office365.com — the email address in the top-right corner is your UPN. Your tenant domain is everything after the @.

That’s the user journey. Five minutes if you’re on the Copilot CLI plugin path, ten minutes via VS Code, less than that if Scout is already on the box.

Build Something With It — Two Samples + The Repo

Asking Work IQ questions in a CLI is fine, but it’s not why the API exists. The actual point is to build things on top of it — automations, custom UIs, integrations that wire Work IQ into where your team already works.

To make that concrete, here are two small samples (~270 lines total) we shipped to a public repo as Day-1 companion code. Both deliberately stay small so you can read them end-to-end, fork, and adapt:

👉 github.com/susanthgit/aguidetocloud-workiq-samples (MIT, fork away)

Sample 1 — Morning brief generator (morning-brief/)

A 190-line Node.js script that runs once at 8am, asks Work IQ three orchestrated questions, and writes a markdown standup brief to disk:

• “Summarise everything that’s happened with Project X in the last 7 days”
• “What’s on my calendar today and tomorrow?”
• “What commitments have I made that I haven’t followed up on?”

Schedule it with Windows Task Scheduler or cron and you’ve got an auto-generated brief in your inbox every morning — built on top of Work IQ’s agent orchestration, not a single CLI question. The script makes three sequential A2A calls and stitches the results.

It’s adaptable. Pipe it into email with nodemailer. Post it to a Teams incoming webhook. Render as HTML and serve. The brief is just markdown — adapt it to your workflow.

Sample 2 — Web-app (web-app/)

A tiny Express server + single-page HTML interface (~270 lines) for asking Work IQ questions in a browser. Demonstrates the embed pattern for adding Work IQ to any internal web app.

The full UX, three screenshots:

The frontend is ~200 lines of vanilla HTML/CSS/JS — no React, no build step. Backend is ~150 lines of Express + MSAL. Multi-turn conversations work via Work IQ’s contextId (the server holds a Map of conversationId → A2A contextId across turns).

The architecture we landed on (and the false starts)

Both samples authenticate via MSAL device-code flow and call the Work IQ A2A REST endpoint directly with a bearer token. Here’s the honest history of how we got there:

The A2A endpoint lives at https://workiq.svc.cloud.microsoft/a2a/. It speaks JSON-RPC 2.0 with an A2A-Version: 1.0 header. You POST a SendMessage method with a question in the parts[].text, get back a task object with artifacts[].parts[].text containing the answer.

A REST API in the same shape is “coming soon” per Microsoft Learn — when it lands, the migration is one endpoint URL change.

Open invitation

These samples are deliberately small + unopinionated. Real production runs would add: retries, structured logging, per-tenant config, secrets management, rate limiting, streaming responses, multi-user OAuth federation. None of that is here. They’re starting points.

If you build something interesting on top of these, send me a link — I’d love to feature what the community builds first.

What It Costs — Copilot Credits Explained

Work IQ API usage is billed through Copilot Credits, a consumption model. There’s no separate per-user licence on top of the M365 Copilot licence the user already needs.

The unit: 1 Copilot Credit = $0.01 USD (source — Microsoft Copilot Studio estimator).

The two cost components:

The per-model token rates published by Microsoft are denominated in credits per million tokens. Expected rates at GA, based on the broader Copilot Credits pricing model:

The new admin-centre cost dashboard that launched with Work IQ is where this gets manageable:

• Choose prepaid or pay-as-you-go billing
• Set spending limits per tenant, group, or user
• See real-time usage per agent and per service
• Handle credit-request workflows when users hit their limits

Work IQ is the first product managed through this dashboard — Copilot Studio and others migrate in over time. If you’ve ever wished M365 admin centre had real cost controls on Copilot consumption, this is the first version of that.

Cost dashboard screenshots will land here once Microsoft ships the new admin-centre Copilot Credits surface (post-GA day). The post is updated when they do.

Plain-English summary on cost:

• Three or four daily Work IQ queries per user is going to be measured in cents per user per day on the GPT-5 mini default. Pennies.
• Heavy multi-turn agent loops on GPT-5.5 with a lot of tool calls can add up — that’s where the spending-limit configuration earns its keep.
• The honest planning posture: turn on PAYG with a per-user daily cap for the first two weeks, watch the dashboard, then formalise budgets.

A worked example — 50-user pilot

Let’s make the abstract concrete. Imagine a 50-user pilot — say, your customer-success team — using a Work IQ-powered agent for a “what’s new on my accounts today?” morning brief each weekday morning. Each brief averages 3 Work IQ calls (Tools + Context + Chat). Numbers are based on the expected GA rates above; verify against your own admin-centre dashboard once GA lands.

A few honest reads on these numbers:

• The Copilot licences are by far the dominant cost. Work IQ consumption is a rounding error on a small pilot at default-model rates.
• Model choice is where things move. GPT-5.5 costs ~15× more per output token than GPT-5 mini. Don’t reach for the powerful model unless the use case demonstrably needs it.
• Output tokens are the lever. A morning brief that returns “in 4 bullets” rather than “in 4 paragraphs” can halve your Chat bill.
• Cap before you scale. Set a per-user daily Work IQ spending limit at $1 or $2 the first two weeks of the pilot. The admin-centre dashboard will tell you whether to relax or tighten before you roll out to the wider org.

What Changes When This Lands — Outlook, Scout, Custom Apps

Work IQ being a layer — not a product end-users open — means the visible changes show up in other Microsoft surfaces over time.

Microsoft Scout — the first Autopilot agent Microsoft announced on 2 June 2026 — builds context powered by Work IQ over time. Per the Scout announcement, Scout “builds context powered by Work IQ, learning how you work, what you care about, and what needs to happen next.” It’s open-source-based (OpenClaw) and lives across Teams, Outlook, OneDrive, SharePoint. When you ask Scout to “block prep time for Thursday’s customer meeting” or “flag any decisions that have been stalled for more than 5 days”, what’s happening underneath is Scout’s reasoning loop calling Work IQ’s Tools, Context, and Chat APIs in a sequence.

Custom apps built by partners and ISVs — every agent platform that supports MCP can now point a tool config at the Work IQ MCP server and gain access to any user’s M365 tenant in a structured way. That includes Claude Desktop, every IDE with MCP support, custom agent frameworks like LangGraph and AutoGen, and any product anyone builds on top of MCP. The bar to integrate is lower than it’s ever been — five lines of JSON config.

Inside the M365 chrome itself — Microsoft signals that more of Outlook’s commitments tracking, Teams’ decision-extraction, OneDrive’s smart-folder behaviour will increasingly be backed by Work IQ as a shared back-end. You won’t see Work IQ as a UI; you’ll see Outlook quietly getting smarter about what you’ve committed to.

What does NOT change — Microsoft Graph is not deprecated. Work IQ is the recommended foundation for new agent applications. For batch jobs, scheduled imports, app-only services, and existing automations that work — stay on Graph. The two coexist for the long haul.

The Honest Limitations

In the spirit of honest > charming, here’s what surprised me on Day 1.

1. Delegated-only auth is a real constraint. If your existing architecture relies on app-only / unattended-agent / service-principal auth (most batch jobs, most scheduled imports), Work IQ is not for you yet. Microsoft has been clear they don’t support it. This rules out a lot of analytics, reporting, and back-office automation patterns. Use Graph for those.
2. Pricing details are still rolling out. The Tools fixed-fee and per-model token rates I cited above are the best community consensus pre-GA. Microsoft’s pricing page and the new admin-centre cost dashboard are the source of truth — verify against your own usage before committing to budgets.
3. The first call is slower than subsequent ones. Semantic-index warmup matters. Build for the warm-path numbers, but flag the cold-path latency to users in any UX where the first query is “instant” expectations.
4. Agents need to be taught to use the resource-path style. The shift from sendMail-as-tool to do_action /me/sendMail-as-resource-path is genuinely different. Your prompts and your agent system messages need updating. Don’t expect a one-line swap to work out of the box.
5. REST is “coming soon” — A2A and MCP are GA today. If your architecture wants plain HTTPS REST and can’t use MCP or A2A, you’re waiting. No date announced.

Top 5 Errors You’ll Hit (And What To Do)

Save yourself the doomscroll. Five errors cover ~90% of the support questions in the first month of using Work IQ. Quick-reference here, full context lives in the relevant sections above.

Two general debug tools worth knowing:

• workiq ask --verbose — prints the conversation ID and request ID; pair with workiq debug <conversationId> to generate a shareable diagnostic link Microsoft support can read.
• workiq logout — clears the MSAL token cache. Useful when you suspect token staleness.

Where To Go Next

Four doors:

1. microsoft/work-iq on GitHub — the source for the CLI, ADMIN-INSTRUCTIONS.md, and the Enable-WorkIQToolsForTenant.ps1 script. Star it.
2. Work IQ overview on Microsoft Learn — canonical conceptual docs, updated frequently.
3. Work IQ API overview on Microsoft Learn — protocol reference (A2A, MCP, REST coming soon) with worked request/response examples.
4. Work IQ MCP overview on Microsoft Learn — the 10-verbs reference and design principles in Microsoft’s own words.

If you build something on Work IQ and want to compare notes — send me a message. I’m planning a follow-up post measuring real-tenant performance on the 80% / 2× claims, and a deeper dive on the cost-management dashboard once a couple of months of usage data is in.

Sources

• Microsoft 365 Blog — Announcing the new Work IQ APIs (2 Jun 2026)
• Microsoft 365 Blog — Introducing Microsoft Scout (2 Jun 2026)
• Microsoft Learn — Work IQ overview
• Microsoft Learn — Work IQ API overview
• Microsoft Learn — Work IQ MCP overview
• Microsoft Learn — Work IQ CLI
• microsoft/work-iq GitHub repo
• microsoft/work-iq ADMIN-INSTRUCTIONS.md
• Microsoft Copilot Studio Estimator (1 Copilot Credit = $0.01 USD anchor)