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

# Microsoft setup for IT admins

> Day-to-day Microsoft sign-in, the optional org-wide Azure app, Power BI tenant settings, and Graph permissions — not Teams messages.

Day-to-day Microsoft in Rivvi is **sign in with your work account**. Each teammate connects their own account. There is no Azure app to register for that path. Start with [Microsoft 365](/connectors/microsoft-365).

This page is the IT-side detail: the optional **Advanced** org-wide app, Power BI's extra tenant setting, and which Graph permissions that app needs.

**Teams is not part of this connection.** Reading or posting Teams messages is not a Microsoft 365 Graph grant. [Add Rivvi to Microsoft Teams](/connectors/microsoft-teams) is a separate install.

<Info>
  There are **two ways to connect Microsoft data**:

  * **Sign in** — default. Each person connects their Microsoft work account. Rivvi sees SharePoint, OneDrive, Excel, Outlook, and Power BI that account can already open.
  * **Advanced org-wide app** — you register an Azure app and paste its credentials under **Settings → Connectors → Microsoft 365 → Advanced**. Use this only if you need unattended, app-identity access.

  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 — Sign in (default)

<Steps>
  <Step title="An admin enables Microsoft 365">
    **Settings → Connectors → Microsoft 365 → Enable**. If you're not an admin, click **Request**.
  </Step>

  <Step title="Each teammate signs in">
    Under **Your account**, click **Connect** and sign in with a Microsoft work or school account. Approve access and you land back connected.
  </Step>

  <Step title="Enable Power BI (if you'll use it)">
    Power BI still needs the tenant setting below if you use an org-wide app. Per-user sign-in uses that person's Power BI access.
  </Step>
</Steps>

You still control, inside Rivvi, which capabilities the agent may use — see [Permissions](/connectors/permissions).

## Option B — Advanced org-wide 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

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 |
| `Calendars.ReadWrite` | Outlook calendars and events             |

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. Rivvi's Microsoft 365 connector does **not** read Teams channel messages. Teams is a [separate Rivvi app](/connectors/microsoft-teams).
</Tip>

### 3. Paste into Rivvi

<Steps>
  <Step title="Open Advanced">
    **Settings → Connectors → Microsoft 365 → Advanced** (or connect [Power BI](/connectors/power-bi) on its own inside that same tile).
  </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 "sign in and you're done" story when you use an **app identity**. 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 (org-wide app)">
    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 returns nothing">
    Confirm `Sites.Read.All` and `Files.Read.All` are added *and* admin-consented. Delegated permissions won't work for this app-identity flow.
  </Accordion>
</AccordionGroup>

## Security notes

* Rivvi's default Microsoft path is **your signed-in account**. The agent can only open what that account can already open.
* 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 an org-wide app, 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 an org-wide app) remove the app under **Enterprise applications** in Entra.

## Next

<CardGroup cols={2}>
  <Card title="Connect Microsoft 365" icon="microsoft" href="/connectors/microsoft-365" />

  <Card title="Power BI only" icon="chart-column" href="/connectors/power-bi" />

  <Card title="Microsoft Teams" icon="microsoft" href="/connectors/microsoft-teams" />

  <Card title="Tool permissions" icon="sliders" href="/connectors/permissions" />
</CardGroup>