> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rivvi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft setup for IT admins

> The complete end-to-end setup for the Microsoft 365 and Power BI connectors — one-click consent, bring-your-own Azure app, Power BI access, and multiple workspaces.

This is the full, end-to-end setup for connecting Microsoft to Rivvi — written for the **Microsoft 365 / Azure administrator** who provisions access. If you just want to connect the tool from the workspace, start with [Microsoft 365](/connectors/microsoft-365); come here when you need the IT-side detail.

One Microsoft connection covers the whole suite — **Power BI, SharePoint, OneDrive, Excel, and Teams** — from a single Azure AD app. You never wire those services separately.

<Info>
  There are **two ways to connect**. Pick one:

  * **One-click admin consent** — fastest. An admin approves Rivvi's app for your tenant once. Best for most organizations.
  * **Bring your own Azure app** — you register your own app and paste its credentials. Choose this if your security policy requires a first-party app, or one-click isn't offered in your workspace.

  Either way, **Power BI needs one extra tenant setting** that consent alone can't set — see [Enable Power BI access](#enable-power-bi-access).
</Info>

## Option A — One-click admin consent (fastest)

If your workspace shows a **Connect with Microsoft** button on the Microsoft 365 connector, this is the path.

<Steps>
  <Step title="Open the Microsoft 365 connector">
    In the Rivvi workspace: **Settings → Connectors → Microsoft 365 → Connect**.
  </Step>

  <Step title="Click “Connect with Microsoft”">
    You're sent to Microsoft's consent screen. **You must be signed in as a Microsoft 365 / Entra admin** who can grant consent for your organization.
  </Step>

  <Step title="Review and accept">
    Microsoft shows the exact permissions Rivvi requests (read-only access to SharePoint sites, files, and Teams messages). Click **Accept** to grant them for your whole organization.
  </Step>

  <Step title="You're returned to Rivvi">
    Rivvi confirms the connection. No app registration, no secrets to copy — Rivvi only records which tenant granted access.
  </Step>

  <Step title="Enable Power BI (if you'll use it)">
    Consent covers SharePoint, OneDrive, Excel, and Teams instantly. Power BI needs one more step — see [Enable Power BI access](#enable-power-bi-access).
  </Step>
</Steps>

<Note>
  One-click grants **read-only** Microsoft Graph access at the organization level. You still control, inside Rivvi, which specific capabilities the agent may use — see [Permissions](/connectors/permissions).
</Note>

## Option B — Bring your own Azure app

Register your own Entra (Azure AD) application and paste three values into Rivvi. This uses the OAuth 2.0 **client-credentials** (service principal) flow — an app identity, not a user login.

### 1. Register the app

<Steps>
  <Step title="Create the app registration">
    In the [Microsoft Entra admin center](https://entra.microsoft.com) → **App registrations → New registration**. Give it a name (e.g. *Rivvi Connector*). Account type **Single tenant** is fine. No redirect URI is needed for the client-credentials flow.
  </Step>

  <Step title="Copy the IDs">
    On the app's **Overview**, copy the **Directory (tenant) ID** and the **Application (client) ID**.
  </Step>

  <Step title="Create a client secret">
    **Certificates & secrets → New client secret.** Copy the secret **Value** immediately — it's shown only once.
  </Step>
</Steps>

### 2. Grant Microsoft Graph permissions

For SharePoint, OneDrive, Excel, and Teams, add **Application** permissions (not Delegated) under **API permissions → Add a permission → Microsoft Graph → Application permissions**:

| Permission                | Enables                                  |
| ------------------------- | ---------------------------------------- |
| `Sites.Read.All`          | SharePoint sites and lists               |
| `Files.Read.All`          | OneDrive files and Excel workbook ranges |
| `Team.ReadBasic.All`      | Listing Teams                            |
| `Channel.ReadBasic.All`   | Listing channels                         |
| `ChannelMessage.Read.All` | Reading channel messages                 |
| `Group.Read.All`          | Resolving Teams and groups               |

Then click **Grant admin consent for \<your org>**. Each permission should show a green "Granted" state.

<Tip>
  Only add the permissions for the services you'll actually use. If you're not using Teams, skip the Teams/Channel permissions. Rivvi asks for read-only access — it never requests write permissions to Graph.
</Tip>

### 3. Paste into Rivvi

<Steps>
  <Step title="Open the connector">
    **Settings → Connectors → Microsoft 365** (or **Power BI** for Power BI only) **→ Connect**.
  </Step>

  <Step title="Enter your three values">
    | Field                             | What to paste                                                       |
    | --------------------------------- | ------------------------------------------------------------------- |
    | **Tenant ID**                     | Directory (tenant) ID                                               |
    | **Client ID**                     | Application (client) ID                                             |
    | **Client secret**                 | The secret's **Value**                                              |
    | **Default Power BI workspace ID** | *(Optional)* Leave blank to use every workspace, or pin one default |
  </Step>

  <Step title="Connect">
    Rivvi verifies the app can reach Microsoft before marking it connected — so a wrong secret or missing permission fails now, not on the first question.
  </Step>
</Steps>

## Enable Power BI access

Power BI is the one exception to the "one click and you're done" story. Microsoft gates the Power BI REST API behind a **separate tenant setting** that neither admin consent nor Graph permissions can turn on. This is a one-time, tenant-wide step done by a **Power BI administrator**.

<Steps>
  <Step title="Turn on service-principal API access">
    In the [Power BI admin portal](https://app.powerbi.com/admin-portal) → **Tenant settings → Developer settings → “Allow service principals to use Power BI APIs.”** Enable it — for the whole organization, or for a security group that contains Rivvi's app (its service principal).
  </Step>

  <Step title="Add the app to your workspaces">
    A service principal can't see a workspace until it's a member. In each Power BI workspace Rivvi should read: **Workspace → Manage access → Add** the app (or its security group) as a **Member** or **Admin**.

    Granting the tenant setting org-wide exposes every workspace automatically; adding per-workspace gives you tighter control.
  </Step>
</Steps>

<Warning>
  If Rivvi says it can't see any Power BI workspaces even though the connection succeeded, this setting is almost always the cause — the app authenticates fine but has no Power BI API access yet. Enable *"Allow service principals to use Power BI APIs"* and confirm the app is a member of at least one workspace.
</Warning>

## Multiple Power BI workspaces

Rivvi works across **every** workspace your app can access — not just one. Different workspaces often carry different sensitivity levels (a clinical workspace vs. a marketing one), and Rivvi treats each independently.

* **Discover them** — Rivvi can list every workspace the app is a member of.
* **Read across all of them** — asking for "my reports" spans all your workspaces; each report is tagged with the workspace it came from.
* **Target one** — you (or the agent) can scope a question to a specific workspace by name.
* **Pin a default** *(optional)* — set a **Default workspace ID** when connecting so ambiguous questions land on your primary workspace. Leave it blank to always work across all of them.

<Tip>
  Add Rivvi's app to a new Power BI workspace at any time — it shows up automatically the next time Rivvi lists workspaces. No reconnecting needed.
</Tip>

## Row-level security (RLS) and SSO

A Power BI dataset with **row-level security** or **single sign-on (SSO)** can't be queried by an app identity — that's a Microsoft platform limit, not a Rivvi one. If the agent hits one, it tells you plainly instead of returning a partial, filtered result. Query a dataset without RLS/SSO, or point Rivvi at the underlying data source.

## Troubleshooting

<AccordionGroup>
  <Accordion title="“Couldn't verify credentials” when connecting (bring-your-own)">
    Usually a mistyped **client secret** (copy the *Value*, not the Secret ID), a wrong **tenant ID**, or admin consent not yet granted on the Graph permissions. Re-check API permissions show a green "Granted" state.
  </Accordion>

  <Accordion title="Connected, but no Power BI workspaces show up">
    The tenant setting *"Allow service principals to use Power BI APIs"* isn't enabled, or the app isn't a member of any workspace. See [Enable Power BI access](#enable-power-bi-access).
  </Accordion>

  <Accordion title="A specific Power BI workspace is missing">
    The app isn't a member of that workspace. Add it under **Workspace → Manage access** as a Member or Admin.
  </Accordion>

  <Accordion title="A dataset query fails with a row-level security message">
    That dataset has RLS or SSO enabled, which an app identity can't query. Use a dataset without RLS/SSO, or query the underlying source.
  </Accordion>

  <Accordion title="SharePoint or Teams returns nothing">
    Confirm the matching Graph **Application** permission is added *and* admin-consented (`Sites.Read.All`, `Files.Read.All`, or the Teams permissions). Delegated permissions won't work for this app-identity flow.
  </Accordion>
</AccordionGroup>

## Security notes

* Rivvi requests **read-only** access to Microsoft Graph. It never asks to modify SharePoint, OneDrive, Teams, or files.
* The only Power BI actions that change anything — refreshing a dataset, exporting a report — are **write** capabilities that ask for your approval every time. See [Permissions](/connectors/permissions).
* With bring-your-own, your app's secret is stored securely for your organization and never shown back to you. Disconnecting removes it.
* You can revoke Rivvi's access any time: **disconnect** in Rivvi, and (for one-click) remove the app under **Enterprise applications** in Entra.

## Next

<CardGroup cols={2}>
  <Card title="Connect Microsoft 365" icon="microsoft" href="/connectors/microsoft-365">
    The connect page for the full suite.
  </Card>

  <Card title="Power BI only" icon="chart-column" href="/connectors/power-bi">
    Grant just Power BI, without the rest.
  </Card>

  <Card title="Tool permissions" icon="sliders" href="/connectors/permissions">
    Control what the agent may do with each capability.
  </Card>

  <Card title="Using connectors in chat" icon="messages" href="/connectors/using-connectors-in-chat">
    See a connected tool at work.
  </Card>
</CardGroup>