How Happeo Integrates with Microsoft

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.

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.

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 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. 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 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, 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, encrypted with Android’s Keystore system. On iOS, tokens are stored securely using 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.