Skip to main content

Microsoft 365

Outlook mail and calendar, OneDrive, SharePoint and Teams chats through Microsoft Graph.

Connect it with: Sign in (OAuth). Microsoft 365's own documentation: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow.

What agents can do​

Connect Microsoft 365 so the agents working your tasks can reach it. With it connected, they can:

  • Read your Outlook calendar to find free time, and create events, if you granted calendar access.
  • Read or send Outlook mail for tasks that work from your inbox, if you granted mail access.
  • Read a Word, Excel or PowerPoint file on OneDrive or SharePoint that a task links to.
  • Read Teams chats for the context of a request, if you granted chat access.

Before you start​

  • A Microsoft 365 work or school account, or a personal Microsoft account (Outlook.com, OneDrive).
  • If your organization requires admin approval for apps, an admin of your Microsoft Entra tenant to approve Jaah once (Enterprise applications > Admin consent requests).
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Microsoft 365​

This is the quickest way in: you sign in to Microsoft 365 and approve what Jaah asks for. You never copy a key.

  1. In Jaah, open Secrets and select New.
  2. Search for Microsoft 365 and select its card.
  3. Give the secret a name you will recognize, such as the account or workspace it reaches, and choose who can use it (see Who can use it).
  4. Select Connect Microsoft 365. Microsoft 365's sign-in window opens.
  5. Sign in to Microsoft 365 if asked, check the access listed, and approve it.
  6. You land back in Jaah on the new secret, which reads Connected once its test passes.

If the button reads Jaah app not configured, this Jaah has no app registered at Microsoft 365 yet. Use your own OAuth app until it does (see Use your own OAuth app).

Scopes Jaah requests​

Jaah asks Microsoft 365 for these scopes, and no others. A scope marked optional is a checkbox on the Connect screen: untick it and agents simply cannot do that part.

ScopeWhy Jaah asks for itRequired
offline_accessStay connected: lets Jaah renew access without asking you againYes
User.ReadRead your profile, so the connection shows whose it isYes
Calendars.ReadWriteRead your calendar and create events when a task asks for itNo — you may untick it
Mail.ReadRead your mail, for tasks that work from your inboxNo — you may untick it
Mail.SendSend mail as you when a task asks for itNo — you may untick it
Files.Read.AllRead OneDrive and shared files agents are pointed atNo — you may untick it
Sites.Read.AllRead SharePoint sites, lists and documentsNo — you may untick it
Chat.ReadRead your Teams chats for contextNo — you may untick it

Connect with an API key​

Microsoft 365 has no API key option in Jaah: connect with the sign-in above.

Use your own OAuth app​

Register your own OAuth app at Microsoft 365 when your company requires apps it controls, or before this Jaah has an app registered there.

  1. Create an OAuth app in Microsoft 365's developer console, https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade (Microsoft 365's documentation).
  2. Set its redirect URI to https://app.jaah.ai/api/credentials/connect/callback (on your own Jaah, its console address followed by /api/credentials/connect/callback).
  3. Give it the scopes in Scopes Jaah requests.
  4. Copy its client ID and client secret.
  5. In Jaah, start a new Microsoft 365 secret, select Use your own OAuth app, paste both values and select Connect Microsoft 365.

The client secret is stored with the connection, encrypted, like any other secret value.

Test the connection​

Select Test on the secret. Jaah calls Microsoft 365's API once (GET https://graph.microsoft.com/v1.0/me?$select=displayName,mail,userPrincipalName) with the stored values, and shows who it answered as, or which value Microsoft 365 refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A signed-in connection hands the agent a live access_token, with access_token_expires_at. Jaah refreshes it before it expires, so an agent never handles a refresh token.

Tell the agent in your task description which secret to use, for example “use the Microsoft 365 secret org/microsoft-365”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Reconnect: when Microsoft 365 ends the grant (a password change, a revoked app, an expired refresh), the secret shows Needs reconnect. Select Reconnect and sign in again; agents get the new token on their next call.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Microsoft 365's side too, revoke Jaah in Microsoft 365's settings.

Limitations​

  • Microsoft has no API keys for user data: you connect by signing in.
  • Agents act as the signed-in user and see only that user's mail, calendar, files and chats.
  • Teams chats (Chat.Read) and SharePoint (Sites.Read.All) need a work or school account; a personal account cannot grant them.
  • Your organization's consent policy can require an admin to approve any of these permissions.
  • Agents can do only what the connected Microsoft 365 account and its granted scopes allow.

Troubleshooting​

Sign-in says Need admin approval

Your organization lets only admins consent to apps. Select Request approval, or ask an Entra admin to grant consent under Enterprise applications > Jaah > Permissions.

Sign-in shows AADSTS50011 The redirect URI does not match

With your own app, add the redirect URI shown on this page, exactly, under Authentication > Web > Redirect URIs.

Test says Microsoft 365 rejected the access token (401)

The grant was revoked or your password changed. Select Reconnect and sign in again.

The secret shows Needs reconnect after about 90 days of no use

Microsoft refresh tokens expire when unused for 90 days or when an admin revokes sessions. Select Reconnect.

Still stuck? Select Test and read the result: it names the value Microsoft 365 refused and the status it answered.

FAQ​

Can I connect a shared mailbox?

Agents reach what the signed-in user can open. Connect as a user with access to the shared mailbox.

Can I give agents read-only access?

Yes. Untick Calendars.ReadWrite and Mail.Send on the Connect screen.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Microsoft 365 account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.