![ms-graph-api icon](/docs/img/components/icons/60/bXMtZ3JhcGgtYXBp.png) # Microsoft Graph API Connector key: ms-graph-api[Source](https://github.com/prismatic-io/components/tree/main/components/ms-graph-api)[API Docs](https://learn.microsoft.com/en-us/graph/use-the-api)[API Changelog](https://developer.microsoft.com/en-us/graph/changelog)[Connector Changelog](#changelog) ## Description[​](#description "Direct link to Description") [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/use-the-api) is a unified REST API that provides access to data across Microsoft 365 services. This component allows interacting with many Microsoft products from a single API endpoint. The Graph API can be explored using the [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) tool. #### API Documentation[​](#api-documentation "Direct link to API Documentation") This component was built using [Microsoft Graph REST API v1.0](https://learn.microsoft.com/en-us/graph/api/overview). ## Connections[​](#connections "Direct link to Connections") ### OAuth 2.0 Authorization Code[​](#oauth "Direct link to OAuth 2.0 Authorization Code") **key: oauth** #### Prerequisites[​](#prerequisites "Direct link to Prerequisites") * A Microsoft Azure account with admin access * Access to the [Microsoft Azure Portal](https://portal.azure.com/#home) #### Setup Steps[​](#setup-steps "Direct link to Setup Steps") 1. Navigate to **Azure Active Directory** > **App registrations** in the [Microsoft Azure Portal](https://portal.azure.com/#home). 2. Create a new application registration. 3. When prompted to select **Supported account types**, select **Accounts in any organizational directory (Any Azure AD directory - Multitenant)** to allow users outside of the organization to authenticate. 4. Go to **Platforms** and add the **Web** platform. 5. Add the OAuth 2.0 callback URL as a **Redirect URI**: `https://oauth2.prismatic.io/callback` 6. Navigate to **Certificates & Secrets** and add a new **Client Secret**. Copy the **value** (not ID) for future use. 7. Locate the **Application (client) ID** on the **Overview** page. #### Configure the Connection[​](#configure-the-connection "Direct link to Configure the Connection") Supply the following values to the **OAuth 2.0** connection: * **Client ID**: The Application (client) ID from the Azure Portal. * **Client Secret**: The secret value copied from Certificates & Secrets. * **Scopes**: The OAuth permission scopes required by the integration. Scopes can be found in the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) or by making test calls in the [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer). * **Authorize URL** and **Token URL**: For single-tenant applications, replace these with tenant-specific URLs. Multi-tenant applications can use the default `/common/` endpoints. **Important**: Ensure the `offline_access` scope is included in the app registration. This scope is essential for receiving refresh tokens. Without it, users must re-authenticate every hour. For more information on authenticating against the Microsoft Graph API, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/graph/auth-v2-user). #### App Verification and Admin Consent[​](#app-verification-and-admin-consent "Direct link to App Verification and Admin Consent") Microsoft requires Azure AD app registrations used in multi-tenant deployments to complete a publisher verification process. This review confirms the app developer's identity, giving end users confidence that they are authorizing a legitimate, verified application. Azure AD app registrations have two distinct verification concepts that affect how users experience the authentication flow. #### Publisher Verification[​](#publisher-verification "Direct link to Publisher Verification") Without publisher verification, the Microsoft consent screen displays **"Unverified"** next to the app name. This can reduce user trust and may trigger security warnings in organizations with strict app access policies. To verify the publisher: 1. Ensure the organization has a [Microsoft Partner Network (MPN) account](https://partner.microsoft.com/) 2. In the [Microsoft Entra Admin Center](https://entra.microsoft.com/), open the app registration 3. Under **Branding & properties**, click **Add a verified publisher** 4. Enter the MPN ID and confirm Once verified, the consent screen displays the organization name with a verified badge instead of "Unverified." #### Admin Consent[​](#admin-consent "Direct link to Admin Consent") Apps requesting **application permissions** (permissions that act without a signed-in user) or high-privilege **delegated permissions** require admin consent before any user in a Microsoft 365 tenant can authenticate. Without admin consent, users see a **"Need admin approval"** error. A tenant administrator can grant consent using either method: **Method 1 — Admin Consent URL:** Navigate to the following URL, replacing `{tenant}` with the Directory tenant ID and `{client_id}` with the Application client ID: [https://login.microsoftonline.com/{tenant}/adminconsent?client\_id={client\_id}](https://login.microsoftonline.com/%7Btenant%7D/adminconsent?client_id=%7Bclient_id%7D) **Method 2 — Microsoft Entra Admin Center:** 1. Navigate to [Microsoft Entra Admin Center](https://entra.microsoft.com/) → **Enterprise applications** 2. Select the app registration 3. Under **Permissions**, click **Grant admin consent for \[organization name]** Delegated vs. Application Permissions Delegated permissions (user-level) typically do not require admin consent unless they are classified as high privilege. Application permissions always require admin consent. Review the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) to identify which permissions require consent. | Input | Notes | Example | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Authorize URL | The OAuth 2.0 Authorization URL for Microsoft Graph API. For multi-tenant applications, use /common/ endpoints. For single-tenant apps, replace with tenant-specific URLs. | https\://login.microsoftonline.com/common/oauth2/v2.0/authorize | | Client ID | The Client ID from the Azure AD application registration. | 12345678-1234-1234-1234-123456789abc | | Client Secret | This is the 'value' (not ID) of the client secret you generated in Azure Portal. | | | Scopes | Space-separated list of OAuth permission scopes. Find available scopes at https\://developer.microsoft.com/en-us/graph/graph-explorer | https\://graph.microsoft.com/User.Read.All offline\_access | | Token URL | The OAuth 2.0 Token URL for Microsoft Graph API. For multi-tenant applications, use /common/ endpoints. For single-tenant apps, replace with tenant-specific URLs. | https\://login.microsoftonline.com/common/oauth2/v2.0/token | ### OAuth 2.0 Client Credentials[​](#oauthclientcredentials "Direct link to OAuth 2.0 Client Credentials") **key: oauthClientCredentials** The OAuth 2.0 Client Credentials flow is designed for service-to-service authentication where no user interaction is required. This flow is ideal for daemon services, background processes, and server-to-server integrations that need to access Microsoft Graph API resources using the application's own identity rather than on behalf of a user. For more information on the Client Credentials flow, refer to the [Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow). #### Prerequisites[​](#prerequisites-1 "Direct link to Prerequisites") * A Microsoft Azure account with admin access * Access to the [Microsoft Azure Portal](https://portal.azure.com/#home) * Administrative consent authority to grant Application permissions #### Setup Steps[​](#setup-steps-1 "Direct link to Setup Steps") 1. Navigate to **Azure Active Directory** > **App registrations** in the [Microsoft Azure Portal](https://portal.azure.com/#home). 2. Create a new application registration or select an existing application. 3. When prompted to select **Supported account types**, choose the appropriate option: * **Single tenant**: Select **Accounts in this organizational directory only** for tenant-specific access * **Multi-tenant**: Select **Accounts in any organizational directory** to allow access across multiple tenants 4. Navigate to **Certificates & Secrets** and add a new **Client Secret**. Copy the **value** (not ID) for future use. 5. Navigate to **API permissions** and add the required Microsoft Graph **Application permissions** (not Delegated permissions): * Click **Add a permission** > **Microsoft Graph** > **Application permissions** * Select the permissions required for the integration (e.g., `User.Read.All`, `Mail.Read`) * Click **Grant admin consent** to approve the permissions (admin consent is required for Application permissions) * Refer to the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) for available Application permissions 6. Locate the **Application (client) ID** on the **Overview** page. 7. Locate the **Directory (tenant) ID** on the **Overview** page. This value is required for tenant-specific endpoints. #### Configure the Connection[​](#configure-the-connection-1 "Direct link to Configure the Connection") Supply the following values to the **OAuth 2.0 Client Credentials** connection: * **Client ID**: The Application (client) ID from the Azure Portal * **Client Secret**: The secret value copied from Certificates & Secrets * **Tenant ID**: The Directory (tenant) ID from the Overview page (not `/common/` - must be tenant-specific) **Important Considerations**: * **Application permissions only**: The Client Credentials flow requires Application permissions (app roles), not Delegated permissions. Application permissions must be granted by an administrator. * **Tenant-specific authentication**: Unlike user-based OAuth flows, the Client Credentials flow requires tenant-specific endpoints and cannot use the `/common/` endpoint. * **No user context**: Actions performed using this connection execute under the application's identity, not on behalf of any specific user. * **Admin consent required**: An organization administrator must grant admin consent for all Application permissions before the connection can obtain tokens. For more information on authenticating against the Microsoft Graph API using the Client Credentials flow, refer to the [Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow). | Input | Notes | Example | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | Base URL | The base URL for the Microsoft Graph API. Depending on your cloud environment, you can choose the correct one [here](https://learn.microsoft.com/en-us/graph/deployments#microsoft-graph-and-graph-explorer-service-root-endpoints). | https\://graph.microsoft.com | | Client ID | Client Id of your Azure application. | 11111111-2222-3333-4444-555555555555 | | Client Secret | Client Secret generated under 'Certificates & Secrets' in your Azure application. | 11111111-2222-3333-4444-555555555555 | | Microsoft Entra ID Endpoint | The Microsoft Entra ID endpoint for the Microsoft Graph API. You can find this in the Azure portal or [here](https://learn.microsoft.com/en-us/graph/deployments#app-registration-and-token-service-root-endpoints). | https\://login.microsoftonline.com | | Scopes | Microsoft Graph API Scopes. | https\://graph.microsoft.com/.default | | Tenant | The tenant ID or name for the Microsoft Graph API. This is the ID or name of the tenant that you are connecting to. | 11111111-2222-3333-4444-555555555555 | | Token URL | Provide a tenant specific OAuth 2.0 token endpoint. | {{#entraIdEndpoint}}/{{#tenant}}/oauth2/v2.0/token | ## Actions[​](#actions "Direct link to Actions") ### Raw Request[​](#rawrequest "Direct link to Raw Request") Send raw HTTP request to Microsoft Graph API. | **key: rawRequest** | Input | Notes | Example | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Connection | The Microsoft Graph API connection to use. | | | Data | The HTTP body payload to send to the URL. | {"exampleKey": "Example Data"} | | File Data | File Data to be sent as a multipart form upload. | \[{key: "example.txt", value: "My File Contents"}] | | File Data File Names | File names to apply to the file data inputs. Keys must match the file data keys above. | | | Form Data | The Form Data to be sent as a multipart form upload. | \[{"key": "Example Key", "value": new Buffer("Hello World")}] | | Header | A list of headers to send with the request. | User-Agent: curl/7.64.1 | | Max Retry Count | The maximum number of retries to attempt. Specify 0 for no retries. | 0 | | Method | The HTTP method to use. | | | Query Parameter | A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1\&key2=value2. | | | Response Type | The type of data you expect in the response. You can request json, text, or binary data. | json | | Retry On All Errors | If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors. | false | | Retry Delay (ms) | The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled. | 0 | | Timeout | The maximum time that a client will await a response to its request | 2000 | | URL | Input the path only (/me/joinedTeams), The base URL is already included (https\://graph.microsoft.com/v1.0). For example, to connect to https\://graph.microsoft.com/v1.0/me/joinedTeams, only /me/joinedTeams is entered in this field. | /me/joinedTeams | | Use Exponential Backoff | Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored. | false | Example Payload for Raw Request[⤓](https://prismatic.io/docs/example-payloads/ms-graph-api/actions/rawRequest.json "Download example payload") Loading… *** ## Changelog[​](#changelog "Direct link to Changelog") ### 2026-04-30[​](#2026-04-30 "Direct link to 2026-04-30") Updated spectral version ### 2026-02-03[​](#2026-02-03 "Direct link to 2026-02-03") * **Added** OAuth 2.0 Client Credentials connection for service-to-service authentication scenarios ### 2025-07-28[​](#2025-07-28 "Direct link to 2025-07-28") * **Clarified** `offline_access` scope requirement for OAuth connection to ensure refresh token support ### 2025-02-27[​](#2025-02-27 "Direct link to 2025-02-27") * **Updated** OAuth documentation with improved setup instructions ### 2023-12-05[​](#2023-12-05 "Direct link to 2023-12-05") * **Standardized** Raw Request action description format ### 2023-03-03[​](#2023-03-03 "Direct link to 2023-03-03") * **Initial release** of Microsoft Graph API component with OAuth 2.0 Authorization Code connectivity and Raw Request action