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

# SharePoint

> Import documents from SharePoint document libraries into AGO

Import Word, PowerPoint, Excel, PDF, and other documents from a SharePoint site. The connector preserves the folder hierarchy, downloads each file, and extracts its text content for use by your agents.

| Feature            | Details                                                            |
| ------------------ | ------------------------------------------------------------------ |
| **Authentication** | Microsoft Entra ID (Azure AD) — OAuth user or app-only credentials |
| **Content type**   | Files in document libraries (Office documents, PDFs, text files)   |
| **Hierarchy**      | Yes (folders preserved as a tree)                                  |
| **Attachments**    | Files downloaded and parsed for text content                       |
| **Multi-language** | No                                                                 |

## Supported File Types

The connector extracts text from these formats:

* **Office documents**: `.docx`, `.doc`, `.pptx`, `.ppt`, `.xlsx`, `.xls`
* **PDFs**: `.pdf`
* **OpenDocument**: `.odt`, `.odp`, `.ods`, `.rtf`
* **Plain text**: `.txt`, `.md`, `.csv`, `.json`, `.xml`, `.html`
* **Other**: `.epub`

Files larger than 50 MB are skipped. Unsupported file types are listed without content.

## Choose a permission mode

AGO supports two ways to grant access to SharePoint, set in **Settings** > **Integrations** > **SharePoint**:

|                      | All sites                                                             | Selected sites                                                                                  |
| -------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Setup**            | Simple                                                                | More complex                                                                                    |
| **Scope**            | Tenant-wide                                                           | Limited to specific sites                                                                       |
| **Azure permission** | `Sites.Read.All`                                                      | `Sites.Selected`                                                                                |
| **Site selection**   | AGO lists all sites automatically                                     | Admin maintains a list of granted site URLs in **Settings** > **Integrations** > **SharePoint** |
| **Best for**         | Quick start, single-site deployments where tenant scope is acceptable | Strict security, when AGO must only reach explicitly authorized sites                           |

Both modes share the rest of the setup (Tenant ID, Client ID, Client Secret, `Files.Read.All` permission).

## Setup — All sites mode (simple)

<Steps>
  <Step title="Register an app in Microsoft Entra ID">
    1. Go to the Azure Portal > **Microsoft Entra ID** > **App registrations** > **New registration**
    2. Give it a name (e.g. "AGO SharePoint Connector")
    3. Choose **Single tenant** (or **Multitenant** if you serve multiple Microsoft tenants)
  </Step>

  <Step title="Add API permissions">
    Under **API permissions** > **Add a permission** > **Microsoft Graph** > **Application permissions**, add:

    * `Sites.Read.All`
    * `Files.Read.All`

    Then click **Grant admin consent**.
  </Step>

  <Step title="Create a client secret">
    Under **Certificates & secrets** > **New client secret**, generate a secret and copy its **Value** (you can only see it once).
  </Step>

  <Step title="Configure AGO">
    In AGO, go to **Settings** > **Integrations** > **SharePoint**, select **All sites (simple)**, and paste:

    * **Tenant ID**
    * **Client ID**
    * **Client Secret**

    Click **Test Connection** and then **Save Configuration**.
  </Step>

  <Step title="Create a knowledge source">
    1. Go to **Knowledge** > **Sources** > **Create**
    2. Select **SharePoint** as the source type
    3. Pick a site from the dropdown
    4. Optionally pick a specific document library, or leave the default
    5. Save and run a manual sync
  </Step>
</Steps>

## Setup — Selected sites mode (limited scope)

In this mode AGO can only access the SharePoint sites your admin has explicitly granted. Microsoft Graph does not return the list of granted sites, so you maintain it manually in AGO's settings.

<Steps>
  <Step title="Register an app in Microsoft Entra ID">
    Same as the all sites mode: create an app registration in Azure Portal > **Microsoft Entra ID** > **App registrations**.
  </Step>

  <Step title="Add API permissions">
    Under **API permissions** > **Add a permission** > **Microsoft Graph** > **Application permissions**, add:

    * `Sites.Selected`
    * `Files.Read.All`

    Then click **Grant admin consent**. At this stage AGO is not yet able to read any site — `Sites.Selected` only gives the *capability* to be granted access on a per-site basis.
  </Step>

  <Step title="Create a client secret">
    Under **Certificates & secrets** > **New client secret**, generate a secret and copy its **Value**.
  </Step>

  <Step title="Configure AGO">
    In AGO, go to **Settings** > **Integrations** > **SharePoint**, select **Selected sites (limited scope)**, and paste the Tenant ID, Client ID, and Client Secret. Click **Save Configuration**.
  </Step>

  <Step title="Grant AGO access to each site">
    For every SharePoint site you want AGO to read, a SharePoint admin runs the following Microsoft Graph call with a token that has the `Sites.FullControl.All` application permission.

    Before running the commands, gather these values:

    | Placeholder            | What to replace with                                                | Example                                |
    | ---------------------- | ------------------------------------------------------------------- | -------------------------------------- |
    | `YOUR_TENANT_ID`       | Your Microsoft Entra (Azure AD) tenant GUID                         | `d70f4450-1444-4109-a8d5-3d5eb596eaff` |
    | `YOUR_ADMIN_CLIENT_ID` | Client ID of the app you registered with `Sites.FullControl.All`    | —                                      |
    | `YOUR_ADMIN_SECRET`    | Client secret of that admin app                                     | —                                      |
    | `YOUR_TENANT`          | Your SharePoint hostname prefix (the part before `.sharepoint.com`) | `useago` for `useago.sharepoint.com`   |
    | `YOUR_SITE_NAME`       | The site path (the part after `/sites/`)                            | `Marketing` for `/sites/Marketing`     |
    | `YOUR_AGO_CLIENT_ID`   | The Client ID of your AGO app registration                          | —                                      |

    <Tabs>
      <Tab title="curl">
        ```bash theme={null}
        # 1. Get an admin token
        TOKEN=$(curl -s -X POST "https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token" \
          -d "grant_type=client_credentials" \
          -d "client_id=YOUR_ADMIN_CLIENT_ID" \
          -d "client_secret=YOUR_ADMIN_SECRET" \
          -d "scope=https://graph.microsoft.com/.default" | jq -r .access_token)

        # 2. Grant AGO read access to a specific site
        curl -X POST "https://graph.microsoft.com/v1.0/sites/YOUR_TENANT.sharepoint.com:/sites/YOUR_SITE_NAME:/permissions" \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "roles": ["read"],
            "grantedToIdentities": [{
              "application": {"id": "YOUR_AGO_CLIENT_ID", "displayName": "AGO"}
            }]
          }'
        ```
      </Tab>

      <Tab title="PowerShell">
        ```powershell theme={null}
        # 1. Get an admin token
        $body = @{
            grant_type    = "client_credentials"
            client_id     = "YOUR_ADMIN_CLIENT_ID"
            client_secret = "YOUR_ADMIN_SECRET"
            scope         = "https://graph.microsoft.com/.default"
        }

        $response = Invoke-RestMethod `
            -Method Post `
            -Uri "https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token" `
            -ContentType "application/x-www-form-urlencoded" `
            -Body $body

        $TOKEN = $response.access_token

        # 2. Grant AGO read access to a specific site
        $body = @{
            roles = @("read")
            grantedToIdentities = @(
                @{
                    application = @{
                        id          = "YOUR_AGO_CLIENT_ID"
                        displayName = "AGO"
                    }
                }
            )
        } | ConvertTo-Json -Depth 5

        $response = Invoke-RestMethod `
            -Method Post `
            -Uri "https://graph.microsoft.com/v1.0/sites/YOUR_TENANT.sharepoint.com:/sites/YOUR_SITE_NAME:/permissions" `
            -Headers @{
                Authorization = "Bearer $TOKEN"
            } `
            -ContentType "application/json" `
            -Body $body
        ```
      </Tab>
    </Tabs>

    Alternatives: [PnP PowerShell `Grant-PnPAzureADAppSitePermission`](https://pnp.github.io/powershell/) or the [CLI for Microsoft 365](https://pnp.github.io/cli-microsoft365/cmd/spo/site/site-apppermission-add/).
  </Step>

  <Step title="Add the granted site URLs in AGO Settings">
    Open **Settings** > **Integrations** > **SharePoint** and, under **Granted SharePoint sites**, paste each site URL the admin granted in the previous step (e.g. `https://contoso.sharepoint.com/sites/Marketing`). Click **Save Configuration**. These URLs populate the site dropdown when you create a knowledge source.

    Repeat this step every time the admin grants AGO access to a new site.
  </Step>

  <Step title="Create a knowledge source">
    1. Go to **Knowledge** > **Sources** > **Create**
    2. Select **SharePoint** as the source type
    3. Pick a site from the dropdown (populated from the granted URLs)
    4. Pick a document library, then browse the folder tree to choose where to start the import
    5. Save and run a manual sync
  </Step>
</Steps>

## Configuration Options

| Setting          | Required | Default         | Description                                                                                          |
| ---------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------- |
| Permission mode  | Yes      | All sites       | All sites or Selected sites — set in Settings                                                        |
| Site             | Yes      | —               | The SharePoint site to import from                                                                   |
| Document library | No       | Default library | The specific library inside the site                                                                 |
| Folder path      | No       | Library root    | Picked via an interactive folder browser; limits the import to a sub-folder, e.g. `Documents/Public` |

## What Gets Imported

* Each folder becomes a parent document
* Each file becomes a child document with its extracted text content
* The web URL of every item is stored as an external link, so users can open the original file in SharePoint
* File metadata (extension, size, MIME type, full path) is preserved

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test Connection returns 401">
    * Verify the **Tenant ID** is the actual tenant GUID, not `common`
    * Check that the **Client Secret** is the secret value (not the secret ID)
    * If the secret is older than its expiration date, generate a new one
    * Ensure admin consent has been granted for the API permissions
  </Accordion>

  <Accordion title="Site dropdown is empty (All sites mode)">
    The Microsoft Search index can be empty on new tenants or take time to populate. Use the URL input that appears below the dropdown — paste your SharePoint site URL (e.g. `https://contoso.sharepoint.com/sites/marketing`) and click **Test access**.
  </Accordion>

  <Accordion title="Site dropdown is empty (Selected sites mode)">
    AGO needs the granted site URLs to populate the dropdown. Open **Settings** > **Integrations** > **SharePoint** and add the SharePoint site URLs your admin granted access to. Each entry is resolved against Microsoft Graph; URLs that fail to resolve are skipped silently.
  </Accordion>

  <Accordion title="Test access returns 403 (Selected sites mode)">
    AGO has not been granted access to this site. Send the curl command shown in AGO to your Microsoft 365 admin. After the grant runs, click **Test access** again. If you keep seeing 403:

    * Verify the application `id` in the grant matches your AGO Client ID
    * Verify the site URL in the grant request is identical to the one you paste in AGO
    * Some tenants take a few minutes for new grants to propagate
  </Accordion>

  <Accordion title="Sync runs but no files are imported">
    * Confirm the app has `Files.Read.All` granted in addition to `Sites.Read.All` or `Sites.Selected` — site permissions alone let you list sites but not download file content
    * Check the configured folder path actually exists in the library
    * In Selected sites mode, confirm the site has been granted to AGO via Microsoft Graph
  </Accordion>

  <Accordion title="Files appear with placeholder text like [Unsupported file type]">
    The file extension is not in the supported list (see "Supported File Types" above). The file is referenced but its content is not parsed.
  </Accordion>
</AccordionGroup>

## Related

* [Knowledge Connectors](./knowledge-connectors) — All available connectors
* [Knowledge Source Management](../features/knowledge-source-management) — Managing sources