Create a new Microsoft OAuth App

Step 1: Sign in to Microsoft Azure and create a "New Registration"

Click "New Registration" and select a name for your app. This will be user-facing (image below).

Use these configurations (image below):

Name: Calendar V1 App (this can be anything and can be changed later)
Supported account types: "Any Entra ID Tenant + Personal Microsoft accounts"
Redirect URI (optional):
- Select "Web"
- URI: https://$REGION.recall.ai/api/v1/calendar/ms_oauth_callback/.
  - Replace $REGION with your Recall.ai Region such as us-west-2.

Finally, press the blue button at the bottom to create your app

For development purpose, see below for moving app to production/submitting for verification

📘
For production
You must verify ownership of the domain used for the Authorized redirect URI. Domain verification is required when publishing your OAuth 2.0 in production.
This URL must not include Recall's domain and should originate from your own app.

Step 2: Update the app's Authentication

After creating the app, go to Manage > Authentication (Preview) > Settings

Check the "ID tokens (used for implicit and hybrid flows)" checkbox

Step 3: Create a new Certificate or Client Secret

📘
Certificate vs Client Secret
You can configure your Microsoft OAuth application with either a certificate or a client secret; you do not need both.
We recommend using a certificate because it provides stronger security and can remain valid for longer, reducing how frequently credentials need to be rotated.
See details below:
Certificate – Recommended

Can be configured with a long expiration period (100+ years)

Generated by you

Client Secret

Only valid for up to 24 months and must be rotated before it expires

Generated by Microsoft

Certificate Path

In your terminal, navigate to a local directory that is outside of a git repo and use the command below to create 2 files:

private.key
certificate.crt

openssl req -new -x509 \
  -newkey rsa:2048 \
  -keyout private.key \
  -out certificate.crt \
  -days 36500 \
  -nodes \
  -sha256 \
  -subj "/CN=Calendar V1 Application"

Then update the permissions of both files

chmod u=rw,go= private.key certificate.crt

Then go to Certificates & secrets > Client secrets > Certificates

Click "Upload certificate"

Upload your certificate.crt file (image below)

Note, the "Description" field doesn't matter

You're done!

Client Secret Path

Go to Certificates & secrets > Client secrets > New client secret (image below)

Fill out these fields (image below):

Description: describe your secret key
Expires: We highly recommend choosing the longest feasible time for expiry (24 months). Once a credential gets expired, existing calendar connections will need to be re-authorized.

Ensure to copy the secret value as this will be needed in a later step

🛑
Your Microsoft client secret will expire — set reminders now
If you decided to use the "Client Secret path" instead of the "Certification path" (above), we highly recommend doing this:
Before it expires
Add reminders 1–2 months and again ~1 week before the expiration date.
If it expires

Microsoft rejects token refresh with this error code (AADSTS7000222)

Recall disconnects affected Outlook calendar connections

Scheduled bots are removed from upcoming calendar meetings

Each affected user must reconnect their calendar via your OAuth flow

To recover

Create a new secret in Azure

Update it in Recall → Platforms → Microsoft

Have affected users reconnect via your OAuth flow

Steps 2 and 3 are required — a new Azure secret alone will not restore calendar connections.

Step 4: Add the "Calendars.Read" API permission

Go to API permissions > "Add a permission" (image below)

Go to Microsoft Graph > Delegated Permissions > Calendars.Read (image below)

Add the "Calendars.Read" API permission for the app (image below)

Step 5: Save your credentials to your workspace in the Recall Dashboard

Go to Overview in Microsoft Azure

Copy your Application (client) ID (image below)

Go to the calendar client credentials dashboard

Once inside the Recall Dashboard:

Paste your Application (client) ID into the Client ID field

Certification path

If you chose the certification path (again, this is recommended), paste the contents from the 2 files you created in Step 3 into their respective fields:

Private key: private.key

Certificate: certificat.crt

Client Secret path

If you chose the client secret path (again, this is not generally recommended), paste the client secret from Step 3:

Save the calendar client credentials in your Recall workspace.

Client Secret: Client secret ID (from Microsoft)

Congratulations! You are done configuring your Microsoft Outlook calendar for Calendar V1 Recall bots. However, there are still a couple more steps to finish in your codebase.

Step 6: Building Microsoft OAuth 2.0 URL

Each user in your application must connect their Outlook calendar via OAuth before using calendar integration. The process for connection is triggered by redirecting user to the OAuth URL.

The URL structure should be as follows:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
    scope={SCOPES}
    &response_mode=query
    &response_type=code
    &state={STATE}
    &redirect_uri={REDIRECT_URI}
    &client_id={CLIENT_ID}

SCOPES
This parameter should be space separated string containing required scopes which are
offline_access, openid, email & https://graph.microsoft.com/Calendars.Read.

Sample value:

offline_access openid email https://graph.microsoft.com/Calendars.Read

REDIRECT_URI
This parameter should be one of the redirect_uris configured in your OAuth 2.0 app.
CLIENT_ID
This parameter should be your OAuth 2.0 app's Application(client) ID property.
STATE
This parameter needs to be a JSON stringified object, which should contain
a. recall_calendar_auth_token: The calendar auth token for the user. (required)
b. ms_oauth_redirect_url: The redirect_uri (should be same as REDIRECT_URI parameter in the url) (required)
c. success_url: The URL to redirect the user to once authentication has completed (optional)
d. error_url: The URL to redirect the user if the authentication errored (optional)

Sample value:

state=JSON.stringify({
  recall_calendar_auth_token: AUTH_TOKEN_HERE,
  ms_oauth_redirect_url: REDIRECT_URI_HERE,
  success_url: https://yourdomain.com/microsoft-calendar-connection/success,
  error_url: https://yourdomain.com/microsoft-calendar-connection/error,
})

Step 7: Submitting Microsoft OAuth Client To Production

Before submitting your Microsoft OAuth Client Application to production, please ensure to update the redirect_uri to be on your own domain (rather than being on recall.ai domain) as Microsoft requires to verify domain ownership of each of the redirect URIs added in the app.

For e.g Add https://your_website_domain/api/ms_oauth_callback as redirect_uri. In the request handler for above URL, return a HTTP redirect response to https://us-west-2.recall.ai/api/v1/calendar/ms_oauth_callback/.

All request parameters should be forwarded as is from your domain to recall.ai's oAuth endpoint.

More documentation on the process of submitting your app for approval is available here: https://learn.microsoft.com/en-us/azure/active-directory/develop/publisher-verification-overview

Troubleshooting

OAuth Flow Stuck on Admin Consent Step

Some Microsoft workspaces are configured to prevent their users from granting OAuth permissions without admin authorization. If this is the case, your user will see an image like the below:

An issue may occur where even after the admin grants permission, users continue to see this pop-up and are unable to give consent to connect their calendar.

The reason for this is theprompt=consentquery parameter, which causes the "approval" prompt to always show up, regardless of whether the app was approved or not.

The solution is to remove the prompt=consent query parameter when you construct your OAuth request.