Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Tymeslot/tymeslot/llms.txt

Use this file to discover all available pages before exploring further.

Tymeslot’s Microsoft integration uses one Azure AD app registration to cover both Outlook Calendar sync and Microsoft Teams video room creation. You register the app once, configure two redirect URIs, and both integrations become available to your users. The same OUTLOOK_CLIENT_ID and OUTLOOK_CLIENT_SECRET environment variables power both features.

​
What this integration provides

  • Outlook Calendar two-way sync — Tymeslot reads your Outlook/Office 365 calendar to calculate availability and writes confirmed bookings back as calendar events with .ics attachments.
  • Microsoft Teams meeting rooms — When a booking is confirmed on an event type configured for Teams, Tymeslot creates a Teams meeting and embeds the join URL in the calendar event and confirmation email.
  • Microsoft Graph real-time subscriptions — With WEBHOOK_BASE_URL configured, Tymeslot registers Graph change notifications so calendar changes appear immediately rather than on a 15-minute polling cycle.

​
Prerequisites

  • A Microsoft Azure account (personal or organisational)
  • Access to Microsoft Entra ID (formerly Azure Active Directory) in the Azure Portal
  • A domain with HTTPS (required for the OAuth redirect URIs and webhook subscriptions)

​
Register the Azure AD app

1

Open App registrations

In the Azure Portal, navigate to Microsoft Entra ID → App registrations and click New registration.
2

Configure the application

Fill in the registration form:
  • Name: Tymeslot (or any label you prefer)
  • Supported account types: Accounts in any organizational directory (Any Microsoft Entra ID tenant – Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)
Leave the Redirect URI blank for now — you will add both URIs in the next step.Click Register.
3

Add both redirect URIs

In your new app registration, go to Authentication → Add a platform → Web.Add both of the following redirect URIs. Both are required — the first is for Outlook Calendar, the second for Teams video:
https://your-domain.com/auth/outlook/calendar/callback
https://your-domain.com/auth/teams/video/callback
Replace your-domain.com with your actual Tymeslot hostname. The URIs must be exact matches — no trailing slashes.Under Implicit grant and hybrid flows, ensure ID tokens is checked.Click Save.
4

Add Microsoft Graph API permissions

Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions.Add all of the following:
PermissionPurpose
Calendars.ReadWriteRead and write to user calendars
User.ReadSign in and read user profile
offline_accessMaintain access when the user is not present
openidSign users in
profileView users’ basic profile
Click Add permissions.If you are deploying for an organisation and have the required Azure AD admin role, click Grant admin consent for [your tenant] to pre-approve the permissions for all users in the directory. This step is optional for personal Microsoft accounts.
5

Create a client secret

Go to Certificates & secrets → Client secrets → New client secret.
  • Description: Tymeslot Production (or any label)
  • Expires: 24 months is a reasonable choice — set a calendar reminder to rotate it before expiry
Click Add.
6

Copy the client secret value immediately

The Value column in the secrets table shows the secret in full only once. Copy it now before navigating away — this is your OUTLOOK_CLIENT_SECRET. After leaving this page, Azure only shows a masked version.
Copy the secret Value now. Once you navigate away from the Certificates & secrets page, Azure permanently hides the full value and you will need to create a new secret. The Secret ID (a GUID shown in the adjacent column) is not the secret — it is just an identifier.
7

Copy the Application (client) ID

Go to Overview. Copy the Application (client) ID — this is your OUTLOOK_CLIENT_ID.
8

Set environment variables

Add these variables to your .env file (or Docker --env flags):
OUTLOOK_CLIENT_ID=<your_application_client_id>
OUTLOOK_CLIENT_SECRET=<your_client_secret_value>
OUTLOOK_STATE_SECRET=<random_string_you_generate>
Generate OUTLOOK_STATE_SECRET yourself:
openssl rand -base64 32 | tr -d '\n'
Restart Tymeslot for the variables to take effect.
OUTLOOK_STATE_SECRET is not a value provided by Microsoft. It is a random string you generate yourself — it protects the OAuth flow against CSRF attacks. It must stay stable across restarts: changing it will invalidate any in-flight OAuth authorisation attempts.

​
Environment variable reference

VariableRequiredDescription
OUTLOOK_CLIENT_IDYesApplication (client) ID from Azure App Registration
OUTLOOK_CLIENT_SECRETYesClient secret Value from Azure App Registration
OUTLOOK_STATE_SECRETYesSelf-generated random string for CSRF protection
WEBHOOK_BASE_URLNoPublic HTTPS base URL for Microsoft Graph real-time subscriptions

​
Real-time calendar push notifications

Without WEBHOOK_BASE_URL, Tymeslot polls Outlook Calendar every 15 minutes via a fallback sweep. For real-time sync, set WEBHOOK_BASE_URL to your Tymeslot instance’s public HTTPS base URL: 
WEBHOOK_BASE_URL=https://tymeslot.your-domain.com
Scheme and host only — no trailing slash, no path. Microsoft Graph performs a validation handshake against this URL when registering subscriptions, so it must be publicly reachable over HTTPS. Leave WEBHOOK_BASE_URL unset on localhost or private network deployments.

​
Connecting the integration

Once the environment variables are in place, users connect Outlook Calendar and Microsoft Teams from Dashboard → Integrations. Each user authorises their own Microsoft account independently — the app credentials are shared across all users of the instance, but each user’s tokens are stored and encrypted separately.

​
Client secret rotation

Azure client secrets expire. When a secret expires, all users’ Outlook Calendar and Teams integrations will fail with authentication errors. Before the expiry date:
  1. Generate a new client secret under Certificates & secrets → New client secret.
  2. Copy the new Value immediately.
  3. Update OUTLOOK_CLIENT_SECRET in your .env and restart Tymeslot.
  4. Delete the old secret from the Azure portal.
Existing connected integrations continue to work after rotation — Tymeslot refreshes tokens automatically using the new secret on the next token exchange.

Build docs developers (and LLMs) love

Get started for freeTalk to us