Microsoft accounts
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.
Work and school accounts (Microsoft 365) and personal accounts (Outlook.com, Hotmail, Live) connect the same way as Google accounts: 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.
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).
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 (personal) or 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.
- In the Microsoft Entra admin center, go to App registrations and choose New registration.
- 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.
- Under Redirect URI, choose Web and enter the URI that
GET /api/workspace/calendar/microsoft/clientshows, which ishttps://<your cloud host>/api/workspace/calendar/microsoft/callback. - 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.
- Under API permissions, add the delegated Microsoft Graph permissions
Calendars.ReadWrite,User.Readandoffline_access(andCalendars.ReadBasicif members will use busy-only connections). For a single-tenant app, choose Grant admin consent so members aren't asked. - Save the Application (client) ID and the secret with the
PUTabove.
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). Disconnecting deletes all of it.
Agents
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). 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.