{"registry_version":"2026.1025.387","generated_at":"2026-10-25T06:27:00Z","content_sha256":"089d16f627d9365e3d0663cc8069203706d7cb23a76c332226e29686968811a5","signed":true,"signature":{"key_id":"ed25519:74ca19268e364242","algorithm":"ed25519","expires_at":"2026-11-24T06:27:09Z","expired":false,"manifest":"/registry/manifest.json"},"entry_sha256":"d671f2757e99919612e9eb5d20a7b42764d1c74edc1ae6125c1a55c36aea307a","entry":{"id":"microsoft/graph-api","name":"Microsoft Graph API access","vendor":"Microsoft","summary":"Give an Entra app permission to call Microsoft Graph (Microsoft 365 mail, calendar, files, Teams, users and more). The gates are choosing least-privilege permissions, getting user or admin consent in every tenant that uses the app, and, for a few metered APIs, linking an Azure subscription.","aliases":["Microsoft 365 API","Office 365 API","Graph API"],"category":"productivity","group":"B","homepage":"https://developer.microsoft.com/graph","docs":["https://learn.microsoft.com/en-us/graph/permissions-overview","https://learn.microsoft.com/en-us/graph/throttling","https://learn.microsoft.com/en-us/graph/metered-api-list"],"status":"researched","last_verified":null,"last_researched":"2026-10-25","sources":[{"id":"permissions","url":"https://learn.microsoft.com/en-us/graph/permissions-overview","title":"Overview of Microsoft Graph permissions","accessed":"2026-10-25","supports":"Delegated vs application permissions; only admins consent to application permissions (Privileged Role Administrator or Global Administrator); user consent depends on tenant policy; least-privilege guidance; high-privilege permissions to avoid; limits of 400 permissions (work/school) or 30 (personal accounts); limited data for inaccessible member objects.","kind":"official"},{"id":"admin-consent","url":"https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent","title":"Grant tenant-wide admin consent to an application","accessed":"2026-10-25","supports":"Roles that can grant consent; admin consent URL format; granting tenant-wide consent may revoke previously granted tenant-wide permissions; programmatic grants take effect immediately.","kind":"official"},{"id":"throttling","url":"https://learn.microsoft.com/en-us/graph/throttling","title":"Microsoft Graph throttling guidance","accessed":"2026-10-25","supports":"429 Too Many Requests with Retry-After; best practices; Data Connect for bulk extraction; throttled requests inside batches are not retried automatically.","kind":"official"},{"id":"metered","url":"https://learn.microsoft.com/en-us/graph/metered-api-list","title":"Metered APIs and services in Microsoft Graph","accessed":"2026-10-25","supports":"Teams APIs no longer metered from 25 August 2025; metered APIs need an active Azure subscription associated with the app; some metered APIs are protected and need a request; assignSensitivityLabel costs USD 0.00185 per call.","kind":"official"},{"id":"errors","url":"https://learn.microsoft.com/en-us/entra/identity-platform/reference-error-codes","title":"Microsoft Entra authentication and authorization error codes","accessed":"2026-10-25","supports":"AADSTS65001, AADSTS65004, AADSTS90094, AADSTS650052 meanings.","kind":"official"},{"id":"publisher","url":"https://learn.microsoft.com/en-us/entra/identity-platform/publisher-verification-overview","title":"Publisher verification overview","accessed":"2026-10-25","supports":"Users may be unable to consent to unverified multitenant apps registered after 8 November 2020 under risk-based step-up consent.","kind":"official"},{"id":"api-terms","url":"https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use","title":"Terms of Use - Microsoft APIs","accessed":"2026-10-25","supports":"Graph is covered; prohibited uses (scraping/building databases beyond need, more than minimum permissions, circumventing limits, advertising use of API data, reselling data, migrating customers away without approval); email APIs limited to sync/backup unless customers grant more; privacy statement requirements; security breach reporting; audit rights; suspension at any time.","kind":"official"},{"id":"teams-export-blog","url":"https://devblogs.microsoft.com/microsoft365dev/announcing-general-availability-of-microsoft-graph-export-api-for-microsoft-teams-messages/","title":"Announcing general availability of Microsoft Graph Export API for Microsoft Teams messages (Microsoft 365 Developer Blog)","accessed":"2026-10-25","supports":"Historic requirement (2021) that Teams export \"protected APIs\" needed a request form beyond permissions and consent.","kind":"official"},{"id":"veeam-protected-api","url":"https://community.veeam.com/cloud-city-107/vb365-protected-teams-api-call-process-changes-4865","title":"VB365 protected Teams API call process changes (Veeam community)","accessed":"2026-10-25","supports":"People report Microsoft retired the Teams protected-API request form and manual approval on 18 May 2023.","kind":"community"}],"allowed_domains":["entra.microsoft.com","developer.microsoft.com","login.microsoftonline.com","portal.azure.com"],"account_model":{"summary":"Graph access belongs to an Entra app registration in your tenant. Each customer tenant that uses the app gets its own service principal and its own consent record, granted by its own users or admins. Delegated permissions act as the signed-in user; application permissions act as the app across the whole tenant.","accounts":[{"name":"Your Entra tenant and app registration","kind":"project","owned_by":"you","required":true,"note":"See microsoft/entra-app-registration."},{"name":"Customer tenant service principal","kind":"other","owned_by":"each customer organisation","note":"Created on first consent; the customer's admin controls consent, user assignment and removal."},{"name":"Azure subscription linked to the app","kind":"billing","owned_by":"you","required":false,"note":"Only for metered APIs (currently the SharePoint/OneDrive assignSensitivityLabel API)."}],"notes":["Personal Microsoft accounts can use only some delegated permissions, and apps that allow personal accounts can request at most 30 permissions."]},"prerequisites":[{"entry":"microsoft/entra-app-registration"},{"entry":"microsoft/publisher-verification","note":"Strongly advised for multitenant apps used by other organisations; otherwise their users may not be able to consent."}],"have_ready":[{"kind":"other","description":"A list of the exact Graph operations your app calls, mapped to the least-privileged permission for each","why":"Microsoft's API terms forbid requesting more than the minimum permissions; over-asking also makes users and admins refuse consent.","needed_for":["choose-permissions"],"auto_check":"none","source":"api-terms"},{"kind":"app_privacy_policy_url","description":"A public privacy statement that explains your data use and links to https://myapps.microsoft.com and/or https://account.live.com/consent/Manage for revoking consent","why":"Required by the Microsoft APIs Terms of Use when users sign in with Microsoft accounts outside a Microsoft-provided sign-in UI.","needed_for":["customer-consent"],"auto_check":"website_live","source":"api-terms"},{"kind":"other","description":"A contact at each customer organisation who holds an admin role that can consent (Privileged Role Administrator for Graph application permissions)","why":"Application permissions and many sensitive delegated permissions can only be granted by an admin.","needed_for":["customer-consent"],"auto_check":"none","source":"admin-consent"}],"steps":[{"id":"choose-permissions","title":"Choose delegated or application permissions, least privilege first","summary":"Use delegated permissions when a user is signed in (the app can never exceed what that user can do). Use application permissions only for background services; they reach all matching data in the tenant. Pick the least-privileged permission listed on each API's reference page and avoid Directory.AccessAsUser.All, Directory.ReadWrite.All and similar broad permissions.","route":"guided","depends_on":[],"gate":"none","url":"https://learn.microsoft.com/en-us/graph/permissions-reference","sources":["permissions"]},{"id":"add-permissions","title":"Add Microsoft Graph permissions to the app","summary":"In App registrations > your app > API permissions > Add a permission > Microsoft Graph, add the delegated and/or application permissions you chose.","route":"guided","depends_on":["choose-permissions"],"gate":"human_submit","url":"https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade","sources":["permissions"]},{"id":"admin-consent","title":"Grant consent in your own tenant","summary":"Select Grant admin consent on the API permissions page. A Privileged Role Administrator can grant any permission; a Cloud Application, Application or AI Administrator can grant everything except Graph application permissions. Granting tenant-wide consent can revoke earlier tenant-wide grants.","route":"guided","depends_on":["add-permissions"],"gate":"human_submit","url":"https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade","recovery":[{"hiccup":"The Grant admin consent button is greyed out.","fix":"You do not hold a role that can consent. Ask a Privileged Role Administrator (needed for Graph application permissions).","source":"admin-consent"},{"hiccup":"Calls return objects with only id and type filled in.","fix":"Your app can see the container but not that member type. Add the least-privileged read permission for that type (for example User.ReadBasic.All).","source":"permissions"}],"sources":["admin-consent"]},{"id":"customer-consent","title":"Get consent in each customer tenant (multitenant apps)","summary":"Customers' users consent at first sign-in where their tenant policy allows. For application permissions, send the customer's admin to https://login.microsoftonline.com/{tenant}/adminconsent?client_id={client-id}. Unverified multitenant apps may be blocked by risk-based step-up consent.","route":"guided","depends_on":["admin-consent"],"gate":"third_party_review","recovery":[{"hiccup":"\"Administrator consent is required.\"","code":"AADSTS90094","fix":"The customer's admin must grant consent through the admin consent URL or Enterprise apps.","source":"errors"},{"hiccup":"\"The user or administrator hasn't consented to use the application.\"","code":"AADSTS65001","fix":"Trigger an interactive sign-in so the user can consent, or ask the admin to grant tenant-wide consent.","source":"errors"},{"hiccup":"The user declined consent.","code":"AADSTS65004","fix":"Ask the user to retry and accept, and explain why each permission is needed.","source":"errors"},{"hiccup":"\"The app needs access to a service that your organization hasn't subscribed to or enabled.\"","code":"AADSTS650052","fix":"The customer tenant lacks the Microsoft 365 service behind that permission; their admin must enable or license it.","source":"errors"},{"hiccup":"Consent screen warns the app is from an unverified publisher and users cannot continue.","fix":"Complete publisher verification for the app.","source":"publisher"}],"optional":true,"sources":["admin-consent","publisher"]},{"id":"metered-billing","title":"Link an Azure subscription (metered APIs only)","summary":"Only needed for metered APIs, currently SharePoint/OneDrive assignSensitivityLabel. Teams APIs stopped being metered on 25 August 2025 and need no billing setup. Some metered APIs are protected and need a request to Microsoft before use.","route":"guided","depends_on":["admin-consent"],"gate":"human_payment","url":"https://learn.microsoft.com/en-us/graph/metered-api-setup","optional":true,"sources":["metered"]},{"id":"test","title":"Test calls and handle throttling","summary":"Try your calls in Graph Explorer, then in code. When throttled, Graph returns 429 with a Retry-After header; wait that long before retrying. Use delta queries and change notifications instead of polling, and Microsoft Graph Data Connect for bulk extraction.","route":"guided","depends_on":["admin-consent"],"gate":"human_login","url":"https://developer.microsoft.com/graph/graph-explorer","recovery":[{"hiccup":"Requests fail with 429 Too Many Requests.","code":"429","fix":"Wait for the Retry-After seconds (or back off exponentially if absent), then retry; retry failed requests from JSON batches yourself.","source":"throttling"}],"sources":["throttling"]}],"outputs":[],"terms_notes":[{"kind":"rules_say","severity":"red","title":"No advertising use of Graph data","text":"You may not use or transfer data from Microsoft APIs, including aggregated, anonymised or derived data, for advertising or marketing (targeting or serving ads).","source":"api-terms"},{"kind":"rules_say","severity":"red","title":"Do not scrape, over-collect or get around limits","text":"You may not scrape or build databases of API data beyond your app's intended scenario, request more than the minimum data or permissions, circumvent Microsoft's limits, or resell or sublicense API data. Violations can lead to suspension or termination.","source":"api-terms"},{"kind":"rules_say","severity":"red","title":"Mail APIs are for sync and backup","text":"Unless customers expressly grant more, Outlook/Exchange mail APIs (including Graph mail) may only be used to sync or back up mail, calendar and contacts.","source":"api-terms"},{"kind":"rules_say","severity":"amber","title":"Data deletion and privacy duties","text":"Get consent before processing, keep stored data current, delete all data when a user leaves or uninstalls your app, and publish a privacy statement at least as protective as Microsoft's.","source":"api-terms"},{"kind":"rules_say","severity":"amber","title":"Breach reporting and audits","text":"Report vulnerabilities and data breaches involving the APIs to secure@microsoft.com, make no public statement without Microsoft's permission, and give Microsoft audit access (up to two full-featured instances) on request or risk losing access.","source":"api-terms"},{"kind":"rules_say","severity":"yellow","title":"Application permissions are tenant-wide","text":"An app with an application permission such as Files.Read.All can read every matching item in the organisation; admins will scrutinise these requests.","source":"permissions"},{"kind":"people_report","severity":"yellow","title":"Teams protected-API form retired","text":"Older guides send you to a Teams \"protected API\" request form. People report Microsoft retired that form and manual approval on 18 May 2023 [to verify for any API you plan to use].","source":"veeam-protected-api"}],"pricing_notes":{"costs":"Metered APIs bill the linked Azure subscription; assignSensitivityLabel costs USD 0.00185 per call. Teams APIs are no longer metered (from 25 August 2025).","notes":"The API list on the metered page is short; other Graph APIs are not on it [to verify per API you use].","source":"metered"},"api_provisioning":{"available":"yes","notes":"An admin's token can grant delegated permissions (POST /oauth2PermissionGrants) and application permissions (POST /servicePrincipals/{id}/appRoleAssignedTo) programmatically; these take effect immediately without review. A human admin must still decide and sign in.","docs":["https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent"],"source":"admin-consent"},"detect":{"packages":["@microsoft/microsoft-graph-client","@microsoft/msgraph-sdk","msgraph-sdk","Microsoft.Graph"]}}}