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.
- In Jaah, open Secrets and select New.
- Search for Microsoft 365 and select its card.
- 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).
- Select Connect Microsoft 365. Microsoft 365's sign-in window opens.
- Sign in to Microsoft 365 if asked, check the access listed, and approve it.
- 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.
| Scope | Why Jaah asks for it | Required |
|---|---|---|
offline_access | Stay connected: lets Jaah renew access without asking you again | Yes |
User.Read | Read your profile, so the connection shows whose it is | Yes |
Calendars.ReadWrite | Read your calendar and create events when a task asks for it | No — you may untick it |
Mail.Read | Read your mail, for tasks that work from your inbox | No — you may untick it |
Mail.Send | Send mail as you when a task asks for it | No — you may untick it |
Files.Read.All | Read OneDrive and shared files agents are pointed at | No — you may untick it |
Sites.Read.All | Read SharePoint sites, lists and documents | No — you may untick it |
Chat.Read | Read your Teams chats for context | No — 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.
- Create an OAuth app in Microsoft 365's developer console, https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade (Microsoft 365's documentation).
- 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). - Give it the scopes in Scopes Jaah requests.
- Copy its client ID and client secret.
- 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.