---
title: Microsoft accounts
description: "Connect Microsoft 365 work accounts and Outlook.com personal accounts, as many as you like, keep their busy time fresh, write bookings with a Teams link, and bring your own Entra app."
section: calendar
order: 25
audience: [user, operator, agent]
sources: [services/nodejs-cloud/lib/calendar/microsoft.ts, services/nodejs-cloud/lib/calendar/microsoft-http.ts, services/nodejs-cloud/lib/calendar/microsoft-write.ts, services/nodejs-cloud/lib/calendar/accounts.ts, services/nodejs-cloud/lib/calendar/duties.ts, services/nodejs-cloud/test/db/calendar-microsoft.test.ts]
features: []
---

Work and school accounts (Microsoft 365) and personal accounts (Outlook.com, Hotmail, Live) connect the same way as
[Google accounts](/docs/calendar/google): as many as you like, each with its own list of calendars. Their busy time
blocks slots on your booking pages, and Venom can write a booking into any calendar you can edit, with a Microsoft
Teams link when the account has Teams.

Nothing contacts Microsoft until you connect an account.

## Connecting an account

Open `/api/workspace/calendar/microsoft/connect` while signed in to Venom Cloud (a **Connect Microsoft** button next to
Connect Google on the Calendar app's Connections page is on its way). Microsoft shows its
account picker, so you can connect a second and third account while signed in to the first. It asks you to allow
Venom to:

- read and write your calendars (`Calendars.ReadWrite`),
- read your basic profile, which names the account by its address (`User.Read`), and
- keep that access while you're away (`offline_access`).

Microsoft sends you back to `GET /api/workspace/calendar/microsoft/callback`. Venom lists the account's calendars,
default calendar first, and starts syncing. The sign-in link is good for 10 minutes and works once, only for the
member who started it. Connecting an account you already connected replaces its sign-in.

Some companies only let users consent to apps an admin has approved. If Microsoft says you need an admin's approval,
ask your Microsoft 365 admin to grant consent to the app, or [bring your own Entra app](#bring-your-own-entra-app).

### Busy-only connections

`/api/workspace/calendar/microsoft/connect?mode=busy` asks for `Calendars.ReadBasic` instead. Venom sees when you are
busy but keeps no titles, and can't book into that account. It refreshes by polling, since Microsoft sends change
notifications only with full read access.

## Choosing which calendars block time

Your default calendar, and other calendars you own and can edit, block time from the start. Calendars shared with you
(a colleague's, a team's) and Birthdays wait for you to switch them on. The switches are the same as for Google:
**Blocks time**, **Tentative counts as busy**, **All-day counts as busy** and **Receives invites**
([Google accounts](/docs/calendar/google#choosing-which-calendars-block-time)).

Events shown as **Free** and cancelled events never block time. Events shown as **Tentative** count as tentative.
Events Venom wrote for your own bookings don't count twice.

## How busy time stays fresh

- **Change notifications.** When your Venom Cloud has a public https address, Venom subscribes to changes on each
  calendar that blocks time. A change shows up within seconds; several changes inside 10 seconds are fetched together.
  Microsoft's subscriptions last just under 7 days, and Venom renews each one a day before it ends.
- **Polling.** Every account is also checked every 5 minutes, or every 2 minutes when Microsoft hasn't sent a
  notification in the last day. A self-hosted Venom without a public address lives on polling alone.
- **Just in time.** Opening a booking page checks again (at most once a minute per account), and so does confirming
  a booking, every time.

Venom reads only what changed since the last check (Microsoft's delta query over the next 120 days). If Microsoft
resets that state, Venom reads the whole window again. A calendar whose delta query Microsoft refuses is read in full
each time instead, which works for personal accounts too.

Microsoft can also tell Venom that a subscription needs attention. Venom renews it when Microsoft asks for
reauthorization, creates it again when Microsoft removed it, and syncs when Microsoft says it missed notifications.

## When an account needs you

If you remove Venom's access, change your password in a way that ends sign-ins, or an admin blocks the app, the
account shows **Reconnect this account** and Venom stops syncing it until you connect it again.

Disconnecting an account in the app deletes its subscriptions at Microsoft and its calendars and cached busy time in
Venom. Microsoft has no way for one app to revoke its own access, so to remove Venom from your account entirely, go
to [account.microsoft.com](https://account.microsoft.com/privacy/app-access) (personal) or
[myapps.microsoft.com](https://myapps.microsoft.com) (work or school).

## Writing bookings

When a booking lands in a Microsoft calendar, Venom creates the event in UTC with the invitee named in its body. For a
**Teams** location, Venom asks Microsoft for a Teams meeting and puts its join link on the booking.

Teams links need a work or school account with Teams. Personal Outlook.com accounts can't make Teams meetings through
Microsoft's API, so for those the event gets the location as text ("Online meeting (link to follow)") and a note in
its body saying why; share a link yourself, or pick a Google calendar with Meet as the event type's destination.

Venom doesn't add the invitee as an attendee of the Microsoft event: Outlook would email its own invitation from your
mailbox, and Venom already sends one. A reschedule moves the same event and keeps its Teams link, and a cancellation
deletes it.

## Bring your own Entra app

Venom Cloud connects through the operator's Entra app, set as `MICROSOFT_CALENDAR_CLIENT_ID` and
`MICROSOFT_CALENDAR_CLIENT_SECRET`. An organisation can use its own app instead: an owner or admin saves it with
`PUT /api/workspace/calendar/microsoft/client` and `{client_id, client_secret}` (from the browser, signed in). The secret is sealed in the org's vault and never shown again.
`GET /api/workspace/calendar/microsoft/client` shows which app is in use and the redirect URI to register, and
`DELETE` falls back to the deployment's app (accounts connected through yours must reconnect). Self-hosters without
the deployment variables must do this before anyone can connect.

1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), go to **App registrations** and choose
   **New registration**.
2. Under **Supported account types**, pick one:
   - **Accounts in any organizational directory and personal Microsoft accounts**: work, school and Outlook.com
     accounts can connect. What a hosted Venom Cloud uses.
   - **Accounts in this organizational directory only**: only your company's accounts. The simplest choice for a
     company, and an admin can consent once for everyone. Venom signs in through `/common`, which works for
     single-tenant apps too.
3. Under **Redirect URI**, choose **Web** and enter the URI that `GET /api/workspace/calendar/microsoft/client` shows, which is
   `https://<your cloud host>/api/workspace/calendar/microsoft/callback`.
4. Under **Certificates & secrets**, create a client secret and copy its **Value** (not its ID). Secrets expire (at
   most 24 months); add a new one and paste it in before the old one ends.
5. Under **API permissions**, add the delegated Microsoft Graph permissions `Calendars.ReadWrite`, `User.Read` and
   `offline_access` (and `Calendars.ReadBasic` if members will use busy-only connections). For a single-tenant app,
   choose **Grant admin consent** so members aren't asked.
6. Save the **Application (client) ID** and the secret with the `PUT` above.

Microsoft sends change notifications to `https://<your cloud host>/api/integrations/calendar/microsoft/notify`. That
address needs no registration in Entra, but it must be reachable from the internet over https.

## What Venom reads and stores

| What | Where it is kept |
|---|---|
| Your address, from your Microsoft profile | the account row, to name it |
| The sign-in tokens | sealed in the org's vault (AES-256-GCM, bound to the account); never shown, logged or put in the audit log |
| The calendar list: names, colours, whether you can edit each, whether it can make Teams meetings | one row per calendar, with your switches |
| Busy blocks of the calendars that block time, from a day ago to 120 days ahead: start, end, all-day, tentative | the busy-time cache |
| Event titles (not for busy-only connections) | the busy-time cache, shown only in your own week view; never on a booking page |
| Microsoft's delta links and subscriptions (each subscription's secret only as a hash) | per calendar |

Venom doesn't read bodies or attachments of your events. Attendees and the location's display name come in the same
answer: for the next days' meetings (not for busy-only connections), Venom People keeps the people they matched, a count
of the rest, and the location text. Once a meeting has ended, an attendee who matched nobody waits in your own People
review list (email and the name Outlook gave) until you decide; one that ended after the sync last saw it is read once
more by its id. **Import past meetings** in People settings reads the last 24 months with a `calendarView` read and the
same permission, only when you press it (see
[People meetings](/docs/cloud/people-meetings#people-you-met-who-are-not-in-people)). Disconnecting deletes all of it.

## Agents {#mcp}

The account tools on the workspace MCP server cover Microsoft accounts too: `calendar_account_list`,
`calendar_calendar_list`, `calendar_calendar_update` and `calendar_account_remove`
([Google accounts](/docs/calendar/google#mcp)). Connecting needs Microsoft's sign-in screen in a browser, so there is no
tool for it.

## For operators

| Variable | What it does |
|---|---|
| `MICROSOFT_CALENDAR_CLIENT_ID`, `MICROSOFT_CALENDAR_CLIENT_SECRET` | the deployment's Entra app. Without them (and without an org's own app), Connect Microsoft explains what to set |
| `VENOM_VAULT_KEYS` | required: tokens and org apps are sealed with it |
| `VENOM_CLOUD_ORIGIN` | the public origin used for the redirect URI and the notification address; notifications need https |
| `MICROSOFT_LOGIN_BASE`, `MICROSOFT_GRAPH_BASE` | tests only: point Venom at a fake Microsoft (https, or http on loopback). Ignored on a production deploy |

Microsoft calls `POST /api/integrations/calendar/microsoft/notify` without a session. Venom answers the validation
handshake when a subscription is created, then checks each notification's `clientState` against its stored hash. The
sweep cron runs the polling and the renewals.
