SharePoint & OneDrive

The SharePoint connector keeps a knowledge base in step with a document library or folder that lives in Microsoft 365. Kumkuat reads the library through Microsoft Graph with permissions a user of your tenant grants once, downloads new and changed files on a schedule, and removes documents whose files were deleted. The connector never writes to SharePoint.

It works with SharePoint Online and OneDrive for Business in the worldwide Microsoft 365 cloud (including GCC) and in Microsoft 365 US Government GCC High and DoD.

How it works

1. A workspace admin enters a Microsoft Entra app registration for the workspace under Workspace → Integrations → Cloud sources. The registration tells Microsoft which application is asking for access, and which Microsoft cloud to sign in to.
2. A user of your tenant clicks Connect SharePoint, signs in with Microsoft, and grants the connector read-only access to the sites and files that user can already see. This creates a connection that belongs to the workspace.
3. On a knowledge base, an editor picks a site → document library → folder through that connection and chooses a sync schedule.
4. Each sync lists the folder, ingests files that are new or modified since the last run, and retires documents whose files are gone.

Connections are workspace-wide; folder selection happens on each knowledge base. One connection can feed several knowledge bases.

Before you start

You need:

• A Kumkuat workspace admin (to save the app registration and manage connections).
• Someone who can create an app registration in the Microsoft Entra tenant that owns the SharePoint site. In most organisations that is an Entra Application Administrator or Global Administrator. If your tenant restricts which permissions users may consent to, that administrator also grants admin consent for the connector once.
• A user account in that tenant who can open the library in a browser. That is the account that will connect. A B2B guest account works, as long as it has been invited into the tenant that owns the site and can read the library.

Why your own app registration?

Microsoft runs its US Government clouds as separate instances. An application registered in the worldwide Azure portal cannot obtain tokens for a GCC High or DoD tenant, and vice versa, so the registration has to be created in the cloud and tenant that hold your data. Many organisations also prefer to own the registration so that they control its secret, its permissions and its lifetime. Kumkuat therefore treats the app registration as a workspace setting rather than a platform-wide one.

Step 1 · Create the app registration

Do this in the Azure portal for the cloud your tenant lives in:

Your Microsoft 365 environment	Portal	Cloud setting in Kumkuat
Worldwide, including GCC	https://portal.azure.com	Microsoft 365 (worldwide, includes GCC)
US Government GCC High	https://portal.azure.us	Microsoft 365 US Government GCC High
US Government DoD	https://portal.azure.us	Microsoft 365 US Government DoD

In Microsoft Entra ID → App registrations → New registration:

1. Name: anything recognisable, for example Kumkuat SharePoint connector.

2. Supported account types: Accounts in this organizational directory only (single tenant).

3. Redirect URI: platform Web, value exactly

   https://api.kumkuat.ai/api/v1/connections/callback/sharepoint

   The Cloud sources page in Kumkuat shows this URI with a copy button. If your workspace runs against a different Kumkuat API host, use the URI shown there.

4. After registering, open API permissions → Add a permission → Microsoft Graph → Delegated permissions and add:

   Permission	Used for
   Sites.Read.All	Finding the site and listing its document libraries
   Files.Read.All	Listing folders and downloading files
   User.Read	Labelling the connection with the connecting user's name
   offline_access	Refreshing access between syncs without a new sign-in

   These are all delegated and read-only. The connector requests no application permissions and no write scope. If your tenant does not allow user consent, click Grant admin consent here.

5. Open Certificates & secrets → New client secret, choose an expiry that suits your rotation policy, and copy the secret value now. It is shown only once.

6. From the Overview page note the Application (client) ID and the Directory (tenant) ID.

Step 2 · Save it in Kumkuat

In Kumkuat, open Workspace → Integrations → Cloud sources. In the SharePoint app registration card:

1. Choose the Microsoft cloud that matches the portal you used.
2. Paste the Directory (tenant) ID, the Application (client) ID and the client secret.
3. Click Save app registration.

The card then reports that the workspace is using its own registration and shows the sign-in authority it will use: login.microsoftonline.com for the worldwide cloud, login.microsoftonline.us for US Government.

The secret is encrypted before it is stored and is never returned by the API or the page. Leaving the secret field blank on a later save keeps the stored secret. When you rotate the secret in Entra, paste the new value and save again; existing connections keep working because the refresh uses the current secret.

Step 3 · Connect

Still on Cloud sources, click Connect SharePoint. A Microsoft sign-in opens for the tenant and cloud you configured. Sign in as the user who can read the library, complete any multi-factor prompt your organisation requires, and accept the permissions. The window closes and the connection appears in the list with the account it was made by.

If the person connecting is a guest in the tenant that owns the site, they sign in through their home organisation as usual; Microsoft issues the token from the tenant that owns the site, which is what the connector needs.

Step 4 · Add a library to a knowledge base

Open the knowledge base, and under Cloud connectors click SharePoint. Select the connection, then:

1. Find the site. Type a keyword, or paste the site's browser URL, for example https://contoso.sharepoint.com/sites/Communications. Pasting the URL is the reliable option in a large tenant, and the only one that works for many guest accounts, because Microsoft's site search only returns sites the search index has associated with the user.
2. Choose the document library (SharePoint calls these drives; most sites have one named Documents).
3. Choose a folder, or Sync entire library.
4. Set the schedule (daily, weekly or manual), the maximum files per run, and whether to include subfolders. Click Add Connector.

The first sync starts on the schedule you chose, or immediately with Sync now on the source.

What gets synced

Aspect	Behaviour
File types	PDF, Word, Excel, PowerPoint, text, CSV, Markdown, JSON and HTML. Other files are skipped.
New files	Downloaded, text extracted, added to the knowledge base
Changed files	Detected by the file's modified time; the previous copy is retired and the new one ingested
Deleted files	The document is retired from the knowledge base, but only when the run listed the whole folder
Per-run limit	The maximum files per run you set (default 50); the next run continues where the last stopped

The connector is careful about deletions. If a run's listing was cut short by the per-run limit, nothing is removed. If a listing comes back empty while the knowledge base still holds synced documents, which usually means access was revoked or the folder was moved, nothing is removed either, and the run reports the reason.

Data handling

• Access is read-only and limited to what the connecting user can already open.
• Tokens and the client secret are encrypted at rest with a key held in Google Secret Manager, and a connection can be disconnected at any time. Disconnecting stops every source that used it; documents already synced remain until you delete them.
• The sync itself makes no model calls. It lists, downloads and extracts text. After a document is ingested, Kumkuat queues its standard automatic tagging, and signal extraction runs only if the knowledge base has it enabled. Automatic tagging can be switched off for a workspace on request, which keeps synced text away from model providers until a user deliberately uses it in a test or a chat.
• Synced files are stored in Cloud Storage and their extracted text in PostgreSQL, in the same US regions as the rest of your workspace. See Data flow.

Removing

• A library from a knowledge base: delete the source on the knowledge base. Documents already synced stay until you remove them.
• A connection: click Disconnect on Cloud sources. Every source that used it stops syncing.
• The app registration: click Remove in the app-registration card. Connections made through it can no longer refresh and must be reconnected once a registration is in place again. Deleting the registration in Entra has the same effect.

Doing it through the API

Everything above is available over the REST API with a workspace API key, which is how an IT team can set the connector up without using the app. Endpoints not yet in the generated reference are listed here.

Save the app registration (workspace admin permission):

curl -X PUT https://api.kumkuat.ai/api/v1/connections/sharepoint/config \
  -H "X-API-Key: $KUMKUAT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "cloud": "usgov",
    "tenant_id": "00000000-0000-0000-0000-000000000000",
    "client_id": "11111111-1111-1111-1111-111111111111",
    "client_secret": "<secret value>"
  }'

cloud is global, usgov (GCC High) or usgov_dod. GET on the same path returns the current configuration without the secret; DELETE removes it. GET /api/v1/connections/providers reports, per provider, whether a connection can be started and which sign-in authority it would use.

Connect: POST /api/v1/connections/sharepoint/auth-url returns an auth_url. Open it in a browser as the connecting user. After consent, the connection is listed by GET /api/v1/connections?provider=sharepoint.

Find the site, library and folder (replace CONNECTION_ID):

# by URL (recommended) or by keyword: {"search": "Communications"}
curl -X POST https://api.kumkuat.ai/api/v1/connections/CONNECTION_ID/sharepoint/sites \
  -H "X-API-Key: $KUMKUAT_API_KEY" -H "Content-Type: application/json" \
  -d '{"site_url": "https://contoso.sharepoint.com/sites/Communications"}'

curl -X POST https://api.kumkuat.ai/api/v1/connections/CONNECTION_ID/sharepoint/drives \
  -H "X-API-Key: $KUMKUAT_API_KEY" -H "Content-Type: application/json" \
  -d '{"site_id": "SITE_ID"}'

# top-level folders of a library; pass "parent_id" to descend
curl -X POST https://api.kumkuat.ai/api/v1/connections/CONNECTION_ID/browse \
  -H "X-API-Key: $KUMKUAT_API_KEY" -H "Content-Type: application/json" \
  -d '{"drive_id": "DRIVE_ID"}'

Add the source to a knowledge base and run it:

curl -X POST https://api.kumkuat.ai/api/v1/knowledgebases/KB_ID/sources \
  -H "X-API-Key: $KUMKUAT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source_type": "sharepoint",
    "source_url": "https://contoso.sharepoint.com/sites/Communications/Shared%20Documents",
    "crawl_config": {
      "connection_id": "CONNECTION_ID",
      "site_id": "SITE_ID",
      "drive_id": "DRIVE_ID",
      "folder_path": "Press/2026",
      "include_subfolders": true,
      "max_docs_per_run": 50
    },
    "schedule_enabled": true, "frequency": "daily", "hour_utc": 6, "minute_utc": 0
  }'

# start a sync now; poll the returned job_id
curl -X POST https://api.kumkuat.ai/api/v1/knowledgebases/KB_ID/sources/SOURCE_ID/crawl \
  -H "X-API-Key: $KUMKUAT_API_KEY"
curl https://api.kumkuat.ai/api/v1/knowledgebases/jobs/JOB_ID -H "X-API-Key: $KUMKUAT_API_KEY"

An empty folder_path syncs the whole library. The job result carries pages_new, pages_updated, pages_removed and pages_skipped_unchanged counters.

Troubleshooting

What you see	What it means	What to do
Connect SharePoint reports not configured	No app registration is saved for the workspace and none is configured platform-wide	Complete Step 2
Microsoft error AADSTS50011 (reply URL mismatch)	The redirect URI on the app registration differs from the one Kumkuat sent	Copy the URI from the Cloud sources card into the registration, platform Web, character for character
AADSTS700016 (application not found in the directory)	The tenant ID or the Microsoft cloud does not match where the app was registered	Check the cloud selector and the Directory (tenant) ID
AADSTS65001 or AADSTS90094 (consent required)	Your tenant does not allow users to consent to this permission set	An Entra administrator grants admin consent on the app registration
AADSTS50020 (user account does not exist in tenant)	The connecting user is not a member or invited guest of the tenant that owns the site	Invite the user as a guest to that tenant, or connect as a user of it
AADSTS50194 (single-tenant app on the common endpoint)	The tenant ID is missing	Enter the Directory (tenant) ID; Kumkuat requires it for a workspace registration
No SharePoint sites found	Microsoft's site search returned nothing for this user, common for guests	Paste the site URL in the finder instead of a keyword
Connection token expired — please re-authorize	The refresh token was revoked, expired, or the app registration or its secret changed	Click Connect SharePoint again
A run reports empty-listing prune skipped	The folder listed no files while synced documents exist	Check that the connecting user still has access and that the folder was not moved

📚

Knowledge bases

Where the synced documents land, and how personas use them.

🔒

Data flow

What is stored where, and what reaches a model provider.

🔑

REST API

Keys, base URL and conventions.