# How Happeo Integrates with Microsoft **This article explains how Happeo integrates with Microsoft services (such as Outlook, OneDrive, and Calendar) and the use cases for those integrations.** ## Microsoft Integrations in Happeo Happeo integrates with Microsoft through the following components: - **User Login** (Single Sign-On with Microsoft) - **Happeo Web Application** - **Happeo Mobile Application** These integrations enable Happeo to access Microsoft services such as **Outlook Mail**, **Calendar**, and **OneDrive**, enhancing the user experience across Pages, Channels, and Search. - With the **OneDrive integration**, users can view and manage their files directly within Happeo. - The **Calendar integration** allows users to view and manage events. - The **Email integration** enables users to view their latest emails and see relevant search results from Outlook. All of these integrations are **user-initiated**, meaning Happeo can only access data when the user explicitly authorizes it. Happeo does **not** have access to a user’s files, calendar, events, or email **without their consent or active participation**. * * * ## OAuth 2.0 Integration with Microsoft Happeo uses the **OAuth 2.0 framework** to securely access Microsoft services through the **Microsoft Graph API**. You can read more about Microsoft’s OAuth 2.0 implementation in their [official documentation](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow). In summary, each integration involves: - **Application credentials:** Identify Happeo as the requesting application. - **Scopes:** Define the level of access being requested (e.g., read email, access calendar). - **Access tokens:** Temporary credentials allowing access to Microsoft APIs on behalf of the user. When combined, this structure allows Happeo to securely request and use Microsoft services on behalf of users, based on their [permissions](https://docs.microsoft.com/en-us/graph/permissions-reference). * * * ## Choosing Between Authorization Code Flow and Implicit Flow Happeo supports two OAuth 2.0 authentication flows for Microsoft integrations: **Authorization Code Flow** and **Implicit Flow**. The choice between them impacts both **security** and **user experience**, and can be configured by admins based on organizational needs. * * * ### Authorization Code Flow (Recommended) This **Authorization Code Flow** is the default and most secure method for integrating with Microsoft services. It uses both **access** and **refresh tokens**, with refresh tokens stored securely on Happeo’s backend—encrypted with Google’s Key Management Service or an equivalent service and stored in a secure database like Cloud SQL. **How it works:** 1. Happeo sends the user to Microsoft’s OAuth endpoint requesting specific scopes. 2. The user logs in and authorizes Happeo. 3. Microsoft redirects the user back with an **authorization code**. 4. Happeo’s backend exchanges the code for: - An **access token** (used by the app) - A **refresh token** (stored securely for future use) 5. When the access token expires, Happeo automatically uses the refresh token to obtain a new one **without user intervention**. **Benefits:** - Access tokens are **never exposed in browser URLs**. - **Long-term access** is maintained via refresh tokens. - Provides a **seamless user experience**, with token refreshes happening in the background. - Only **authenticated users** can request or refresh tokens (user session verification required). **Best for:** Organizations that prioritize **security**, **stability**, and **a smooth experience** for their users. * * * ### Implicit Flow (Client-Side) The **Implicit Flow** manages all tokens directly in the browser, eliminating the need for server-side storage. While this simplifies implementation, it comes at the cost of **reduced long-term access** and **weaker security**. This flow is typically used by organizations that choose not to handle tokens on the backend. **How it works:** 1. Happeo sends the user to Microsoft’s OAuth endpoint with requested scopes. 2. The user logs in and authorizes Happeo. 3. Microsoft redirects back with an **access token** in the URL. 4. Happeo stores the token in the browser’s **session storage**. 5. When the token expires, the flow must be re-initiated, requiring the user to be logged into Microsoft. **Considerations:** - **No refresh tokens** – access is short-lived and must be re-authorized often. - **Access tokens are visible in URLs** and stored in the browser, posing **security risks**. - If the user logs out of Microsoft, Happeo will need to re-request access, leading to pop-ups or interruptions. **Best for:** Use cases where **server-side storage is not preferred** or where **short-term access** is sufficient. * * * ### How to enable the Implicit Flow: Admins can enable the implicit flow by: 1. Clicking their avatar and going into **Admin Settings**. 2. Selecting **Advanced control** from the menu. 3. Going to **OAuth2** and toggling **Implicit OAuth2**. * * * ## Privacy and Security At Happeo, **we prioritize user privacy in all our integrations with Microsoft**. All API calls are made directly from the user's browser to Microsoft. The data is combined and rendered in the user's browser, making it appear as a seamless part of the Happeo experience — without passing through Happeo’s servers. To support different security needs, we offer admins the flexibility to choose between the **Authorization Code Flow** and the **Implicit Flow**. When tokens are stored on Happeo’s backend, they are **securely encrypted**, and **no Happeo employee** has access to them. Access to production databases is strictly limited and tightly controlled. * * * ## Data flow in Search AI When a user performs a search in Happeo: - The search begins client-side, with requests sent to Happeo’s search and any enabled federated search connectors (e.g. Microsoft OneDrive). - At this stage, the data returned by the search connectors remains on the client side. If **Search AI** is enabled: - While API calls to Google services are made client-side, the search query and the results from the **enabled integrated sources**(e.g. Microsoft OneDrive) are passed to Happeo’s backend. - The backend sends this information, along with a prompt, to **Gemini** (Google’s AI model) to generate the AI answer. - Happeo does not store the document content returned in these results. Instead, it keeps only **document identifiers** to support Happeo features (if enabled), such as suggesting documents to link within Happeo. This ensures AI-powered search remains accurate and helpful without compromising data security. 🔎 Check out our [**Admin Settings: Search**](https://help.happeo.com/hc/en-us/articles/14444863143569-Admin-Settings-Search) article to learn how to manage which integrated sources are included or excluded from AI generation. * * * ## Microsoft scopes requested by Happeo Happeo requests access to Microsoft Graph scopes based on the **features a user chooses to enable**. Only the **minimum required scopes** are requested for each integration. Below are the possible scopes: **Outlook (Mail):** - **Mail.ReadBasic** – Allows viewing of basic email metadata (e.g., sender, subject). Does **not** allow access to email bodies, previews, or attachments. **Calendar:** - **Calendars.Read.Shared** – Allows viewing of events in calendars that the user has shared access to. - **Calendars.ReadWrite** – Allows creation and editing of calendars and events. **OneDrive:** - **Files.Read** – Allows viewing of the user’s files and folders. - **Files.ReadWrite** – Allows creating, editing, and uploading files and folders. Happeo ensures that **only the necessary scopes** are requested depending on which Microsoft services (Mail, Calendar, or OneDrive) are in use, respecting both user privacy and security. #### Can Happeo see my files, calendar events, or emails? Happeo or any of its employees **cannot see or search** your OneDrive, Microsoft Calendar, or Outlook. A client-side application stores relevant tokens in the browser on your computer and combines the data inside your computer with the Happeo Application. #### What libraries does Happeo use? Happeo uses Microsoft’s official libraries for the OAuth 2.0 flow and to connect to the Microsoft Graph APIs. * * * ## FAQ ### Authentication & Access Control #### What happens if I revoke Happeo’s access from my Microsoft account directly? If you revoke Happeo’s access from your Microsoft account (via your Microsoft account settings), Happeo will no longer be able to load or display your Microsoft data (such as emails, calendar events, or OneDrive files). The next time you access those features in Happeo, you’ll be prompted to **re-authorize the integration** by signing in and granting the necessary permissions again. #### How can I review or remove the permissions I’ve granted to Happeo? You can review or remove the permissions you've granted to Happeo in two ways: - **As a user:** Click your **avatar** from the main navigation and go to your **User Settings**  [**Integrations**](https://app.happeo.com/mysettings/integrations). Check which Microsoft services (e.g., Mail, Calendar, OneDrive) you’ve authorized. You can disconnect or re-authorize them from there. - **As an admin:** Click **avatar** from the main navigation and go to **Admin Settings >**[**Integrations**](https://app.happeo.com/admin-v2/integrations) to view and manage the Microsoft integrations enabled for your organization. You can toggle specific integrations on or off. #### If I change my Microsoft password, will the Happeo integration break? It depends on which OAuth 2.0 flow your organization is using: - **Authorization Code Flow:** No, the integration will generally continue to work. According to [Microsoft’s documentation](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens), changing your password does not immediately revoke refresh tokens for confidential clients (like Happeo). However, if the refresh token expires or is explicitly revoked by the admin or user, re-authorization will be required. - **Implicit Flow:** Yes, changing your Microsoft password will break the integration. Since this flow doesn’t use refresh tokens, you’ll need to re-authorize Happeo after the password change to regain access. #### How can I tell if the access token has expired? It depends on the authentication flow your organization is using: - **Authorization Code Flow:** Expired access tokens are refreshed silently in the background using a refresh token, so in most cases, you won’t notice when the token expires. However, if the **refresh token** has also expired (or is invalidated), you’ll be redirected to the Microsoft login page to re-authorize access. - **Implicit Flow:** You’ll know the access token has expired when Happeo prompts you to re-authorize by displaying an **“Authorize”** button and redirecting you to the Microsoft login page. Since this flow doesn’t support refresh tokens, access expires frequently and requires manual re-authentication. * * * ### Token Management & Behavior #### How long are access tokens valid in Happeo before they expire? Access token lifetimes are **determined by Microsoft, not Happeo**. The exact validity period depends on your organization’s Microsoft 365 configuration and policies. Once an access token expires, Happeo will either refresh it automatically (with Authorization Code Flow) or prompt you to re-authorize (with Implicit Flow). #### What happens to my Microsoft data in Happeo when the token expires and can't be refreshed (e.g., due to logout or permission revocation)? Happeo only stores **refresh tokens** and the **list of authorized scopes**—it does not store your actual Microsoft data. When a token can’t be refreshed (for example, after you log out or revoke permissions), **Microsoft widgets and Microsoft search will no longer work** in Happeo until you re-authorize the integration. #### What happens if Happeo fails to refresh the token — will I lose access to Microsoft services in the app? **Yes**, you’ll temporarily lose access to Microsoft services in Happeo if the token refresh fails. However, you can **restore access** at any time by **re-authorizing the integration**, after which all connected Microsoft services will work again. * * * ### Data Handling & Compliance #### Where is data cached, if at all, when displaying Microsoft content in Happeo? Happeo **does not cache any Microsoft content**. All data is fetched in real time from Microsoft whenever you access it, ensuring **no copies are stored** within Happeo. #### What happens to my Microsoft-related data in Happeo if I delete my Happeo account? Happeo only stores **refresh tokens** and the **list of authorized scopes**—not your actual Microsoft data. When you delete your Happeo account, the stored **refresh token is permanently removed** from Happeo’s database, ending its access to your Microsoft services. * * * ### Mobile & Cross-Device Behavior #### Is token storage handled differently on mobile vs desktop (e.g., mobile keychain vs browser storage)? Yes. On desktop, the **access token is stored in the browser’s session storage**. On Android, tokens are stored in [SharedPreferences](https://developer.android.com/training/data-storage/shared-preferences), encrypted with [Android’s Keystore system](https://developer.android.com/training/articles/keystore.html). On iOS, tokens are stored securely using [Keychain Services](https://developer.apple.com/documentation/security/keychain_services). #### If I authorize Microsoft access on one device, do I have to do it again on another? With **Authorization Code Flow**, you **do not need to re-authorize** Microsoft on multiple web browser sessions, as Happeo can use the stored **refresh token** to maintain access. However, the **mobile app uses a different authorization flow**, so you will need to **authorize again** when using it for the first time.