
Integrations
Microsoft Graph Permissions for AI Apps: Delegated vs. Application Access
Delegated versus application Graph permissions, the tenant setting that overrides the admin-consent flag, AADSTS65001, and Sites.Selected.
TL;DR
If your agent acts for one named user, ask for delegated permissions, ask for the smallest set that works, and build the product on the assumption that some admin will never say yes. Delegated access is capped at what the signed-in user could do anyway, which is the only version of this an enterprise security team will sign off on quickly.
Mail.Send, Mail.ReadWrite, Calendars.ReadWrite and Files.ReadWrite are all flagged in Microsoft's reference as
not requiring admin consent. That flag decides less than you think. A tenant can restrict user consent to
permissions it has classified as low impact, and the default low-impact set is openid, profile, email
and offline_access. Mail.Send is not in it.
The usual reaction is to reach for application permissions instead, which turns "read this rep's calendar" into "read every calendar in the tenant" and guarantees the admin review you were trying to dodge.
We're not saying you can avoid admins. We're saying a request an admin can grant in ninety seconds is a different product from one that needs a security review.
Concretely: register multi-tenant, point at /organizations, keep the first sign-in down to basic profile
and offline_access, add the working scopes later with incremental consent, and wire the /adminconsent
endpoint before your first customer asks for it.
Overview
Take a scheduling assistant sold to mid-market consultancies. It watches a consultant's calendar, drafts the follow-up mail after a client call, and files the countersigned proposal into that deal's SharePoint site. The hard part isn't the model, and it isn't Graph. Graph is a pleasant REST API with good docs. The hard part is that every customer is a separate Microsoft Entra tenant with its own opinions about what an outside application may do, and your onboarding funnel now runs through a person you have never met.
This is where most Microsoft 365 integrations stall. Not at GET /me/events, but three weeks earlier, when a
user clicks Connect and gets AADSTS65001 and a support ticket lands in your queue saying "the integration
doesn't work." It works fine. Nobody consented.
We're going to assume you know how OAuth authorization code flow works and how refresh tokens behave; that ground is covered elsewhere and repeating it wastes your time. This is specifically about Entra's consent machinery, which puts a tenant administrator directly inside your onboarding funnel. If you've already built the same feature against Gmail, our walkthrough of sending mail from an agent as the end user is the closest comparison. The shapes rhyme, but Google's hard gate is verification and Microsoft's is the tenant administrator, and they fail at different points in your funnel.
The rule we'd start from: an agent that acts for one identifiable person should hold delegated permissions and nothing else. Every application permission you add is a promise to your customer's security team that you will never misuse tenant-wide access, and that promise costs weeks.
Delegated or Application
Microsoft's permissions model has two kinds, and choosing wrong is the most expensive mistake available here.
Delegated permissions, per the Graph docs, "let the application act on behalf of a signed-in user. However, the application can't access anything the signed-in user couldn't access." The effective privilege is the intersection of what you were granted and what that person can already do. If the consultant can't read the managing partner's calendar, neither can your agent, no matter what your app registration says.
Application permissions work "without a signed-in user present," and the docs are blunt about the consequence:
"The application can access any data that the permission is associated with." The delegated Mail.Send
displays to a user as "Send mail as a user." The application-permission version displays to an administrator
as "Send mail as any user." One of those sentences gets approved in a meeting. The other one starts a meeting.
| Delegated | Application | |
|---|---|---|
| Acts as | one signed-in user | the app itself |
| Ceiling | intersection with that user's own access | everything the permission covers, tenant-wide |
Mail.Send reads as | "Send mail as a user" | "Send mail as any user" |
Admin consent for Mail.Send | not required by the permission's own flag | required |
Files.ReadWrite | exists | does not exist; the app-only equivalent is .All |
Table 1 — The same capability, two very different asks. Display strings and admin-consent flags are from the Graph permissions reference.
That last row is worth pausing on. There is no application-permission form of Files.ReadWrite, because
"the signed-in user's own files" is not a concept that survives the removal of the signed-in user. To get
app-only access to files you move to Files.ReadWrite.All, which means every file in the tenant. The model is
telling you something: if the job is scoped to a person, the app-only path doesn't have a scoped version to
offer you.
Microsoft says so directly. "From a least-privilege perspective, the delegated permission model is the recommended approach whenever it meets the application's requirements." For an agent doing one user's work, it meets the requirements.
One conflation is worth killing before the next section, because it is what sends teams to application permissions by mistake. "Delegated" and "user-consented" are different axes. Delegated describes the kind of permission: a signed-in user is present at call time and the grant is capped by that user's own access. Admin consent describes who authorised it, and a tenant administrator can consent to a delegated permission on behalf of everyone in the tenant. That produces one tenant-wide grant and removes the consent screen for individuals, and it still leaves the per-user ceiling exactly where it was.
| A user consents | An admin consents for the tenant | |
|---|---|---|
| Delegated permission | One grant for one user, capped by that user's own access | One grant covering every user, each call still capped by the calling user's access |
| Application permission | Not available; these require an administrator | One grant, no user present, no per-user ceiling |
Table 2 — Permission kind and consent authority are independent axes. The cell that worries a security team is the bottom right, not the top right.
So "we need an admin to approve this" is not a reason to switch to application permissions. It is a reason to get a delegated grant approved tenant-wide, which is the same scope list the user would have seen, read once by one person. The two paths differ in who clicks, not in what the agent can reach.
Figure 1 — The only question that matters is whether a named user is present at call time. An agent that runs on someone's behalf has an answer, and it points left.
The Registration, and the Two Errors You Will Meet
For a product sold to other companies, the registration is multi-tenant: in the portal, Supported account types becomes "Accounts in any organizational directory." Your app object still lives in your tenant. What gets created in the customer's tenant, on first consent, is a service principal, and that object is what their admin later reviews, restricts or deletes.
Because the sign-in request can't know which tenant the user belongs to before they type their address, it
goes to a shared authority. Microsoft documents two for multi-tenant apps: https://login.microsoftonline.com/common
for "any organizational directory and personal Microsoft accounts," and https://login.microsoftonline.com/organizations
for work or school accounts only. Use /organizations unless you genuinely intend to support consumer
Microsoft accounts, because a personal account that wanders into your enterprise flow produces a support
ticket nobody enjoys. Once you know the tenant, subsequent calls can use the tenant id directly.
Then there are the two failures. Everyone hits both.
AADSTS50011 is the redirect URI. The identity platform reference calls it InvalidReplyTo: "The reply
address is missing, misconfigured, or doesn't match reply addresses configured for the app." Matching is exact
string comparison against what you registered, so a trailing slash, http where you registered https, or a
port that shifted when your dev server restarted all produce the same wall. Register every environment's URI
explicitly. Microsoft's troubleshooting guidance for this
code
also notes that a newly added URI can take a few minutes to take effect, which is exactly long enough to
convince you the fix didn't work.
AADSTS65001 is consent, and its internal name is more informative than its message: DelegationDoesNotExist.
"The user or administrator hasn't consented to use the application with ID X. Send an interactive
authorization request for this user and resource." There is no delegation record for this user and this
resource. Either nobody ever completed the interactive flow, or you added a scope after they did and are now
silently requesting something that was never granted. The sibling code AADSTS90094 is the honest one:
AdminConsentRequired.
Two details save real time here. Request offline_access explicitly if you want refresh tokens; on the v2
endpoint your app "must explicitly request the offline_access scope, to receive refresh tokens." And decide
early between dynamic scopes and /.default. The .default scope "signals that consent should be prompted
for all required permissions listed in the application registration," and you cannot mix the two styles:
scope=https://graph.microsoft.com/.default Mail.Read is an error. Dynamic scopes are what make incremental
consent possible, so for a product that grows features over time, dynamic is usually right, with
prompt=consent available to force a re-ask when you add one.
Getting Consent, Gracefully
Here is the thing that catches teams who read only the permissions reference. The admin-consent flag on a permission is not the whole answer. The tenant's user-consent setting is.
Microsoft documents three settings. Disable user consent entirely. Allow user consent "for apps from verified publishers, for selected permissions," the middle option, which limits users to permissions the tenant "classifies as low impact." Or allow user consent for any app, for any permission that doesn't itself require admin consent, which is the legacy default.
Now look at what low impact means out of the box. The default classification covers openid, profile,
email and offline_access. That's basic sign-in. Under that middle setting, Mail.Send is not
user-consentable, regardless of its own flag. You can't tell from outside which setting a given tenant runs,
so treat "delegated permissions don't need an admin" as a convenience you sometimes get, never a design
assumption.
Which means the graceful path has to exist from day one. Two pieces do the work.
The first is the admin consent endpoint, which grants a set of permissions for the whole tenant in one action:
GET https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
&redirect_uri=https://app.example.com/ms/admin-consent
&state=12345On success Entra redirects back with admin_consent=True, tenant, scope and your state. The docs are
emphatic about one thing: "Never use the tenant ID value of the tenant parameter to authenticate or
authorize users. The tenant ID value can be updated and sent by bad actors to impersonate a response to your
app." Treat the whole query string as a hint, confirm from your own session, and verify by making a real Graph
call. Note also that tenant here cannot be common, because personal accounts can't grant admin consent.
The second piece is Entra's own admin consent workflow, which you get for free if the customer has enabled it.
When a user can't consent, they can send a request to designated reviewers, who approve or deny it by mail.
Your job is to not fight it: when you see AADSTS65001 or AADSTS90094, don't loop the user back into the
same failing authorize call. Show them what happened, name the permissions in plain language, and give them a
copyable admin consent URL to forward.
Figure 2 — The consent path most products treat as an error and should treat as a state. The admin's grant and the user's connection are two separate events, and both need a UI.
Design for the admin as a user of your product. They will see one screen, once, and decide. Put the permission list, the reason for each one, and a link they can forward in that screen. An agent that asks for four scopes it can justify will clear a review that an agent asking for nine will not.
Publisher Verification and the Unbadged Consent Screen
Publisher verification "gives app users and organization admins information about the authenticity of the developer's organization." When it's done, "a blue verified badge appears in the Microsoft Entra consent prompt for the app." Without it, your consent screen is a dialog from an unidentified company asking to send mail as the person reading it.
Getting the badge takes a verified Microsoft AI Cloud Partner Program account associated with the tenant where
the app is registered, a publisher domain that isn't *.onmicrosoft.com, an email domain that matches or is
DNS-verified in that tenant, and an Application Administrator or Cloud Application Administrator completing
the process with multifactor authentication. It is procurement work, not engineering work, and it takes longer
than you think, so start it the week you decide to build.
It also has teeth beyond aesthetics. Admins "can configure user consent policies that include publisher verification status as primary policy criteria," and Microsoft notes that where risk-based step-up consent is enabled, users can't consent to most newly registered multi-tenant apps that aren't publisher verified. If you're weighing this against Google's equivalent process, our post on Google's OAuth verification and CASA assessment covers that side. We think Microsoft's is the lighter of the two, and it blocks fewer apps outright. It just blocks them at the tenants you most want as customers.
Asking for Less
The single most effective thing you can do to your consent screen is delete a scope from it.
Send mail without reading it. Mail.Send is a separate permission from Mail.ReadWrite, and an agent that
drafts a follow-up and sends it does not need to read the mailbox. If you want the user to review drafts, that
still costs Mail.ReadWrite; if the agent sends directly, it doesn't. Splitting the two across separate
product tiers, requested incrementally, is a real option and a cheap one.
Use Sites.Selected instead of Sites.ReadWrite.All. For the proposal-filing half of our scheduling
assistant, this is the whole game. Sites.Selected grants nothing on its own. Access to a given site or list
is granted afterwards by an administrator, per resource, with a role of read, write, owner or
fullcontrol, and it can be removed per resource by deleting that grant without touching the consent. In the
delegated case "both the application and user permissions are calculated and then intersected, which means
that the application can never exceed the user's permissions." Two independent ceilings, and the customer
controls one of them without talking to you. That is a much easier conversation than "read and write all site
collections."
For Teams, use resource-specific consent. RSC lets an authorized user "give an app access to data of a specific instance of a resource type" instead of every instance in the tenant. A team owner can grant access to team A and not team B. It is Teams-specific and it will not help you with mail, but where it applies it converts a tenant decision into an owner decision.
The pattern underneath all three is the same one that shows up in Slack's split between user tokens and bot tokens, which we wrote about separately: pick the credential whose ceiling is a person or a resource, not the one whose ceiling is the workspace.
The scope list is the sales conversation. Whatever you put in scope= is what a stranger reads on the
day they decide whether your product exists inside their company. We'd cut it to the bone and add back by
incremental consent, feature by feature, after the account is live.
Throttling and Staying in Sync
Two runtime surprises are worth knowing before you ship, because both change your architecture rather than your error handling.
Graph throttles with 429 Too Many Requests and a Retry-After header, and the guidance is to wait exactly
that many seconds rather than improvising: "Backing off requests using the Retry-After delay is the fastest
way to recover from throttling because Microsoft Graph continues to log resource usage while a client is being
throttled." Immediate retries make it worse, and they count.
The limits that will actually bite an agent are Outlook's, which apply per app-and-mailbox pair. Exceeding them for one mailbox "doesn't affect the ability of the application to access another mailbox." The documented per-mailbox limits are 10,000 API requests in a 10-minute period, four concurrent requests, and 150 MB of upload (PATCH, POST, PUT) in a 5-minute period. Four concurrent requests is the number that surprises people. An agent that fans out eight parallel Graph calls to assemble context is already over, for one user, on one mailbox. Microsoft also notes that JSON batching sends up to four individual requests from a batch in parallel, which keeps a batch inside that limit by construction. Graph's throttling guidance further warns about "a large number of requests from a particular application across all tenants," so a noisy customer can degrade a quiet one if you share a client id and don't rate-limit per tenant yourself.
For keeping state fresh, the choice is push or pull, and the right answer is usually both. Change notifications
are event-driven, "instead of them polling Microsoft Graph." Delta query is the pull model, where a response
carries an opaque @odata.deltaLink you replay later to get only what changed. Subscriptions expire fast on
Outlook resources: a maximum of 10,080 minutes for message, event and contact subscriptions, dropping to 1,440
minutes when the notification carries resource data, with a ceiling of 1,000 active subscriptions per mailbox
across all applications. Renewal is your problem, and a missed renewal is a silent data gap.
So treat notifications as a doorbell and delta as the source of truth. Microsoft recommends the pairing explicitly, saying applications can use it to "nearly eliminate (only for supported resources) the need to frequently poll Microsoft Graph." A notification tells you something moved. The delta call tells you what.
your webhook --> queue (tenant+user+resource) queue --> delta call using stored deltaLink (on 429: wait Retry-After, repeat) delta --> local state + new deltaLink --> agent reads local state A renewal timer resubscribes before expiry; a missed renewal is a silent gap. -->
Figure 3 — Notifications as the trigger, delta as the truth. The renewal timer is the part teams forget, and its failure mode is quiet.
What to Ask For on Day One
Our position, stated plainly, because "it depends" helps nobody at registration time.
Register multi-tenant against /organizations. Register every redirect URI you will ever use, exactly, in all
environments. Start publisher verification immediately; it is the longest lead item and it is paperwork.
At first sign-in, request User.Read offline_access and nothing else, so the connect button works for the
widest possible set of tenants. Add the working scope with incremental consent at the moment the user asks for
the feature, and keep that list to Mail.Send, then Calendars.ReadWrite, then Sites.Selected if you file
documents. Not Mail.ReadWrite unless a human reviews drafts in your UI. Not Files.Read.All. Never an
application permission for work that has a signed-in user attached to it.
Build three screens you'd rather not build: consent needed, admin approval pending, and connected-but-scope-missing. The third one is the one that turns into support tickets, because everything looks fine until the agent tries the one call it wasn't granted.
And store the grant per user per tenant, not per tenant. An admin's tenant-wide consent and one consultant's connection are different facts with different lifetimes, and conflating them is how an offboarded employee's calendar keeps getting read.
Conclusion
Microsoft's consent model is more bureaucratic than Google's and more honest about it. The bureaucracy is mostly Entra handing your customer's administrator a real decision, with a real display string, about a real scope. We think that is the right design, and we think the correct response is to make the decision small: delegated permissions, one or two scopes, a verified publisher badge, and a clear screen for the administrator who has thirty seconds.
Everything downstream follows from that choice. Delegated access is capped by the user, so a compromised agent
is bounded by one person's reach rather than a tenant's. Sites.Selected hands the customer a revocation
switch you don't control. Four concurrent requests per mailbox is a constraint you can design around once, or
discover in production repeatedly.
For the per-user half of this, Agentic Fabriq's developer edition holds the shape we'd build anyway: your own
end users each get an external user id you choose, they authorize at the provider themselves, credentials land
in a vault and never touch your servers, and each unit of work mints a short-lived user-scoped token rather
than holding a long-lived credential. A connection row exists from the moment you start the flow, so
status == "connected" is the only thing worth showing a user as connected.
POST /api/v1/apps/{app_id}/external-users/{uid}/oauth/{provider}/initiate
{"connection_id": "default", "scopes": ["...optional..."]}Provider slugs there are surfaces rather than vendors, so Microsoft 365 arrives as several of them: Outlook mail, Microsoft Calendar, Teams chat and SharePoint, each with its own tool list and its own Graph scopes beside each tool. Which of them are connectable on a given deployment, and whether a connection runs through Fabriq's provider app or one you register yourself, is what the capabilities endpoint reports rather than something to hardcode. Where it reports your own app, the Entra registration above is yours to build, and the per-user connection model is the same either way.
The closing position: if a human is on the other end of the request, ask for delegated permissions and the shortest scope list that does the job. Every step away from that is a step toward a security review, and security reviews are measured in weeks.
Sources
- Overview of Microsoft Graph permissions — delegated versus application access, effective permissions, and the least-privilege recommendation.
- Microsoft Graph permissions reference — display strings and admin-consent flags for Mail.Send, Mail.ReadWrite, Calendars.ReadWrite, Files.ReadWrite and Sites.Selected.
- Configure an application to be multitenant — supported account types, and the
/commonversus/organizationsauthorities. - Microsoft Entra authentication and authorization error codes — AADSTS50011 InvalidReplyTo, AADSTS65001 DelegationDoesNotExist, AADSTS90094 AdminConsentRequired.
- Scopes, permissions, and consent in the Microsoft identity platform —
/.default, dynamic versus static consent,prompt=consent, andoffline_access. - Admin consent on the Microsoft identity platform — the
/adminconsentendpoint, its parameters, the response, and the warning about trusting thetenantvalue. - Configure the admin consent workflow — reviewers, request expiration, and the user-facing request experience.
- Configure how users consent to applications — the three tenant user-consent settings and the default behaviour.
- Configure permission classifications — the default low-impact set of
openid,profile,emailandoffline_access. - Publisher verification — the verified badge, CPP and domain requirements, and risk-based step-up consent.
- Microsoft Graph throttling guidance — 429 handling,
Retry-After, and the two throttling scenarios. - Microsoft Graph service-specific throttling limits — Outlook per-mailbox limits and JSON batching concurrency.
- Selected permissions for OneDrive and SharePoint — how Sites.Selected grants are made per resource and the roles available.
- Set up notifications for changes in resource data — subscription lifetimes for Outlook resources and the per-mailbox subscription ceiling.
- Use delta query to track changes in Microsoft Graph data — the pull model,
@odata.deltaLink, and pairing delta with change notifications.