Microsoft 365 Integration

Connect Ascent to Microsoft 365 so your team can send email and turn inbound messages into tickets, all through your own Microsoft mailbox using the Microsoft Graph API.

Overview

The Microsoft 365 integration lets you:

• Send Ascent email (ticket notifications, replies, and test messages) through your Microsoft 365 / Exchange Online mailbox.
• Monitor a mailbox and automatically create or update tickets from inbound email.
• Send from and monitor shared mailboxes (for example, a support@ helpdesk address) in addition to the connected primary mailbox.
• Archive processed emails into a dedicated folder so they aren't re-processed.
• Optionally sync your own tenant's directory and licenses — pull Microsoft 365 users into Contacts and subscribed license SKUs into the Software module. This is opt-in and off by default. See Directory & license sync.
• Optionally connect each client's own Microsoft 365 tenant — sync that client's users into their Contacts and their license SKUs into their Software, directly from the client's page. See Sync a client's own Microsoft 365 tenant.

Email is built on Microsoft Graph mail APIs and is enabled as soon as you connect a mailbox. Directory and license sync is a separate, opt-in step that needs extra admin-consented permissions. The integration does not sync calendars and is not a single sign-on provider.

Navigate to the integration

1. In the left sidebar, open Admin > Integrations (the nav item requires permission to manage integrations, typically the Owner or Admin role).
2. Select Microsoft 365.

The configuration page is laid out as five numbered steps — App Registration, Connect Account, Mailbox Configuration, Email Sync Settings, and Test & Status — followed by an optional Directory & License Sync card.

Prerequisites

• A Microsoft 365 / Exchange Online mailbox.
• Access to the Microsoft Entra admin center to register an application (typically a Global Administrator or Application Administrator).
• Permission to manage integrations in Ascent (typically the Owner or Admin role).

Required Microsoft Graph permissions

Register the app with these delegated Microsoft Graph permissions. The page lists them at the bottom under Required Microsoft Graph Permissions.

Permission	Purpose
Mail.ReadWrite	Read and write mail (read inbound, move processed messages)
Mail.Send	Send mail as the connected user
Mail.ReadWrite.Shared	Access shared mailboxes
Mail.Send.Shared	Send from shared mailboxes

During the OAuth sign-in, Ascent also requests the offline_access, openid, and profile scopes so it can refresh tokens and read the connected account's address. You only need Mail.ReadWrite.Shared and Mail.Send.Shared if you plan to use shared mailboxes.

Setup

Step 1: Register an app in Microsoft Entra

1. Open the Microsoft Entra admin center and go to App registrations > New registration (the page includes an Open Entra Portal link).

2. Give the app a name (for example, Ascent).

3. Under Supported account types, choose single-tenant if this app is only for your organization, or a multi-tenant option if you'll use the common tenant.

4. Set the Redirect URI (Web platform) to your instance's callback URL:

   https://your-instance.goascent.app/api/integrations/microsoft365/callback

   The Ascent page shows the exact redirect URI to use for your instance under the Required Microsoft Graph Permissions card. It must match exactly.

5. Register the app, then copy the Application (client) ID and, if using a single tenant, the Directory (tenant) ID.

Step 2: Add API permissions and a client secret

1. In the app's API permissions, add the delegated Microsoft Graph permissions listed in Required Microsoft Graph permissions above. Grant admin consent if your tenant requires it.
2. In Certificates & secrets, create a New client secret and copy the Value immediately (it is shown only once).

Step 3: Save credentials in Ascent (Step 1 card — App Registration)

1. On the Microsoft 365 integration page, fill in the App Registration card:
   • Application (Client) ID
   • Client Secret
   • Tenant ID (optional) — enter your Directory (Tenant) ID for a single-tenant app, or leave it as common for a multi-tenant app.
2. Click Save Credentials. Once saved, the card shows Credentials configured and the fields become read-only.

Step 4: Connect your account (Step 2 card — Connect Account)

1. In the Connect Account card, click Connect Microsoft 365.
2. You're redirected to Microsoft to sign in and authorize the requested permissions.
3. After approval, you return to Ascent and the card shows Connected with the connected mailbox address and an Active badge.

To remove the connection later, click Disconnect in this card. To remove all credentials and settings, use Delete Configuration in the Test & Status card.

Mailbox configuration (Step 3 card)

The Mailbox Configuration card controls which addresses Ascent sends from and monitors.

Setting	Description
From Email Address	Mailbox that outbound email is sent from. Choose the connected primary mailbox or an added shared mailbox.
From Name	Display name shown on outbound email (for example, Support Team).
Mailbox to Monitor	Mailbox whose incoming email is processed — the primary mailbox or a shared mailbox.
Shared Mailboxes	Additional mailboxes you have access to. You must have Send As permission to send from a shared mailbox.

To add a shared mailbox, enter its address (for example, [email protected]) and click Add. Ascent verifies access before adding it; if it can't reach the mailbox, it shows an error reminding you that you need Send As or Full Access permissions. For a dedicated helpdesk mailbox, the page recommends connecting directly with that mailbox account, which needs its own Exchange Online license.

Click Save Mailbox Settings to persist these choices.

Email sync settings (Step 4 card)

The Email Sync Settings card controls how inbound email is fetched and turned into tickets.

Setting	Description
Enable Email Sync	Automatically fetch new emails on a schedule.
Sync Interval	How often to check: every 1, 5, 15, or 30 minutes, or every hour.
Monitor Folder	Which folder to watch — Inbox by default, or any folder in the connected mailbox.
Create Tickets from Emails	Automatically create tickets from new emails (see Tickets).
Archive Processed Emails	Move processed emails to a separate folder so they aren't processed again.
Archive Folder	The destination for processed emails (shown when archiving is enabled).

When Archive Processed Emails is enabled you must choose an archive folder before saving. You can select an existing folder or click Create "processed-by-ascent" folder to have Ascent create and select one for you.

Click Save Settings to apply.

note

Enabling Microsoft 365 email sync turns off Ascent's platform-managed inbound email for the organization, so the two never both create tickets from the same messages.

Test and status (Step 5 card)

The Test & Status card lets you verify the connection and monitor sync health.

• Send Test Email — enter an address and click Send to deliver a test message from your configured mailbox.
• Sync Status — shows Last Sync (relative time, or Never) and whether sync is Active or Disabled. If the last sync failed, the error message is displayed here.
• Refresh — re-checks the connection and sync status.
• Delete Configuration — removes all Microsoft 365 credentials and settings.

How email-to-ticket works

When email sync is enabled, Ascent periodically reads new messages from the monitored folder and routes them:

1. A new email that doesn't match an existing ticket can create a new ticket (when Create Tickets from Emails is on).
2. A reply that matches an existing ticket is added to that ticket's conversation.
3. Processed messages are moved to the archive folder if archiving is enabled.

Directory & license sync

Beyond email, Ascent can keep one client's records in step with their Microsoft 365 tenant. This is opt-in and turned off by default, so existing email-only setups are unaffected. When enabled, it does two things:

• Users → Contacts — your client's Microsoft 365 tenant users are created and kept up to date as Contacts on the chosen client.
• License SKUs → Software — the tenant's subscribed Microsoft 365 licenses are recorded in the Software module, including how many seats are purchased.

note

Pick the client whose tenant this is carefully — everything synced is attached to the target client you choose. A target client is required; you can't turn a sync on without one.

Extra permissions

Directory sync needs two additional Microsoft Graph permissions that are not part of the email setup, and both require an administrator's consent:

Permission	Purpose
User.Read.All	Read the tenant's user directory
Organization.Read.All	Read the tenant's subscribed license SKUs

Ascent only asks for these when you opt in, so connecting for email alone never prompts for them. After you grant them once, the access is preserved automatically — you won't be asked to re-consent on every sync.

Turn it on

In the Directory & License Sync card:

1. Click Grant directory permissions and approve the Microsoft consent prompt (an administrator must approve). Your email connection keeps working throughout.
2. Choose a Target Client — the client this tenant belongs to.
3. Turn on Sync tenant users to contacts and/or Sync license SKUs to software.
4. Click Save Sync Settings.
5. Optionally click Run Sync Now to sync immediately instead of waiting for the next scheduled run.

The card shows when users and licenses were each last synced and any error from the most recent run.

How often it runs

Once enabled, syncs run automatically on a schedule — user sync about every 6 hours and license sync about every 12 hours — in addition to any Run Sync Now you trigger.

Avoiding duplicates

Re-running a sync updates existing records instead of duplicating them. Users are matched first by their Microsoft 365 identity (so renaming or changing an email doesn't create a second contact) and then by email address within the target client, so a contact you already added by hand is updated rather than duplicated. Users without an email address are skipped.

Disconnecting Microsoft 365 turns the sync toggles back off.

Sync a client's own Microsoft 365 tenant

The directory sync above connects your own Microsoft 365 tenant. If you manage clients who each have their own Microsoft 365 tenant, you can connect each client's tenant separately and keep that client's records in step with it — without touching your own email or directory setup. When connected, Ascent:

• Adds the client's tenant users as Contacts on that client, and keeps them up to date.
• Records the client's subscribed Microsoft 365 licenses in that client's Software list, including how many seats are purchased.

This connection is read-only — Ascent only reads the directory and license information. It never sends or reads email in the client's tenant.

Before you start

• You connect a client's tenant from the client's own page, not the Admin Integrations page.
• You choose how the connection authenticates, right on the client's Microsoft 365 card:
  • A dedicated app per client (default, recommended for MSPs) — register a Microsoft Entra app for that client and paste its Application (client) ID and client secret into the card. This keeps each client isolated and avoids adding external/guest users to your own tenant.
  • Reuse your organization's Microsoft 365 app — turn on Reuse organization's Microsoft 365 app to use the app you configured for the org-level integration instead. This is convenient if you only manage a single tenant. Prerequisite: your organization's Microsoft 365 app registration must already be configured under Admin → Integrations → Microsoft 365. If it isn't, the card says so and links you straight to that page — the per-client connection reuses those app credentials.
• A global administrator of the client's tenant must approve the connection. The permissions requested are read-only: read the user directory and read subscribed licenses.
• The connection's redirect URL must be registered on the Microsoft Entra app you use (see Register the redirect URL below) — typically a one-time setup.

Register the redirect URL

In addition to the email callback URL, add this per-client redirect URI to your app in the Microsoft Entra admin center (App registrations → your app → Authentication → Web → Redirect URIs):

https://your-instance.goascent.app/api/integrations/client-microsoft365/callback

Replace the host with your own instance's API URL. It must match exactly, and it is separate from the email integration's .../api/integrations/microsoft365/callback URL — register both.

Connect a client's tenant

1. Open the client in Ascent (Clients → select the client).
2. In the sidebar, find the Microsoft 365 card.
3. Pick how to authenticate:
   • Dedicated app (default): enter the client's Application (client) ID and client secret. If the app is registered as single-tenant, also enter its Tenant ID; leave it blank for a multi-tenant app.
   • Reuse organization's Microsoft 365 app: turn the toggle on. If your org app isn't configured yet, use the Configure Microsoft 365 app link to set it up first.
4. Click Connect Microsoft 365 and complete the Microsoft sign-in. A global administrator of the client's tenant must approve the read-only directory permissions.
5. After approval you return to the client's page and the card shows the connected tenant (its domain).

Choose what syncs and run it

On the Microsoft 365 card for a connected client:

1. Turn on Sync users to contacts and/or Sync licenses to software (both are on by default once connected).
2. Click Save.
3. Optionally click Run Sync Now to sync immediately rather than waiting for the next scheduled run.

The card shows when users and licenses were each last synced and any error from the most recent run. As with the org-level sync, runs also happen automatically on a schedule — user sync about every 6 hours and license sync about every 12 hours.

Re-running a sync updates existing records instead of duplicating them, and users without an email address are skipped.

Reconnect or disconnect

• Reconnect re-runs the Microsoft approval if the connection expires or was revoked.
• Disconnect removes the client's Microsoft 365 connection. Contacts and software that were already synced are kept — only the live connection and its stored access are removed.

note

Each client's connection is independent. Connecting one client's tenant doesn't affect your own email/directory setup or any other client.

Troubleshooting

Symptom	What to check
OAuth fails or returns an error	Confirm the redirect URI in Entra exactly matches the one shown on the page, and that admin consent was granted for the delegated permissions.
Directory or license sync isn't running	Make sure you clicked Grant directory permissions (admin consent for User.Read.All and Organization.Read.All), selected a Target Client, and turned on the relevant toggle. Use Run Sync Now and review the last-synced error.
Can't connect a client's own tenant	Confirm the per-client redirect URI (.../api/integrations/client-microsoft365/callback) is registered on your Entra app, and that a global administrator of the client's tenant approved the read-only directory permissions.
"Microsoft 365 app credentials are not configured for this organization"	You turned on Reuse organization's Microsoft 365 app but the org-level app isn't set up. Either configure it under Admin → Integrations → Microsoft 365 (use the link on the card), or turn the toggle off and enter a dedicated per-client Application (client) ID and client secret instead.
A client's tenant sync isn't updating	On the client's Microsoft 365 card, confirm the Sync users / Sync licenses toggles are on, click Run Sync Now, and review the last-synced error. Use Reconnect if the connection expired.
Can't add a shared mailbox	Verify you have Send As or Full Access on that mailbox; consider connecting directly with the mailbox account (it needs an Exchange Online license).
Test email fails	Make sure the account is connected and the chosen From Email Address is a mailbox you can send as.
Sync isn't running	Confirm Enable Email Sync is on, then use Refresh and review the Last Sync error message.
Connection dropped	Re-run Connect Microsoft 365 to re-authorize; expired or revoked tokens require a fresh sign-in.

Tips

• Use a dedicated helpdesk mailbox (such as support@) rather than a personal inbox.
• Request only the permissions you need — skip the .Shared scopes if you won't use shared mailboxes.
• Rotate your client secret before it expires. Because the App Registration fields become read-only once credentials are saved, use Delete Configuration in the Test & Status card first, then re-enter the new credentials.

For other email options and the full list of integrations, see the Integrations Overview. If you don't use Microsoft 365, Ascent also supports a generic SMTP/IMAP connection.