Data Sources

Panel → Settings → Data Sources (/settings/connectors) connects your external systems read-only into the knowledge base (RAG). Nothing is changed or deleted in the source systems — content is only read and indexed.

General flow

1. Open Settings → Data Sources. A Connected sources list sits on top, an Add new connection section below.
2. Pick the source type to add (SQL · Google Drive · OneDrive · Dropbox · Notion · Zendesk · OneNote).
3. Each source form has a How to connect? button — the source-specific steps and field help are available right in the panel too.
4. Fill the fields and press Save & connect. Then use Test (verify), Sync (re-pull) and Content (browse indexed documents).
5. Set how often it re-pulls with Sync interval (min) and full refreshes with Full re-sync.

Two ways to connect (OAuth sources)

For Google Drive, OneDrive, OneNote and Notion there are two paths:

Below we give the detailed steps for each source. For BYO, the one-click flow just needs your Client ID + Client secret in the panel.

Databases (SQL)

Read-only SQL sources: PostgreSQL · MySQL · SQL Server (MSSQL). The result of a SELECT query is indexed row by row.

Step by step: creating a read-only user

So the agent can never change anything in your database, create a new user with SELECT-only privileges (ideally on a read replica). By engine:

PostgreSQL:

CREATE USER semagent_ro WITH PASSWORD 'a-strong-password';
GRANT CONNECT ON DATABASE your_database TO semagent_ro;
GRANT USAGE ON SCHEMA public TO semagent_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO semagent_ro;
-- so future tables are readable too:
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO semagent_ro;

MySQL / MariaDB:

CREATE USER 'semagent_ro'@'%' IDENTIFIED BY 'a-strong-password';
GRANT SELECT ON your_database.* TO 'semagent_ro'@'%';
FLUSH PRIVILEGES;

SQL Server (MSSQL):

CREATE LOGIN semagent_ro WITH PASSWORD = 'a-strong-password';
USE your_database;
CREATE USER semagent_ro FOR LOGIN semagent_ro;
ALTER ROLE db_datareader ADD MEMBER semagent_ro;

1. Run the statements above to create the user (choose your own password).
2. If your server is IP-restricted, allow inbound connections from SemAgent's egress IP (173.212.244.210) in your firewall / pg_hba.conf / cloud "authorized networks".
3. Fill in host, port, database, user, password in the panel.
4. In Query, write a SELECT (or WITH) that returns the content to index — e.g. your products, FAQ or knowledge table. Write queries are rejected.
5. For incremental pulls, set an updated-at column (updated_at) in Incremental column; only changed rows are fetched.
6. Press Save & connect → Test to verify.

Cloud storage & documents

Google Drive, OneDrive, OneNote and Notion. Ways to connect: (1) the platform's central one-click OAuth (if your operator set it up); (2) one-click with your OWN OAuth app (BYO — recommended): you enter just Client ID + Client secret in the panel and press "Save & Connect"; SemAgent runs the consent flow with your app (no need to mint a refresh_token by hand); (3) manual token (you mint and paste it yourself). For BYO you must add the redirect URI below to your app — otherwise you get a redirect_uri_mismatch error. The Client secret you enter is stored encrypted and never shown back.

Google Drive

One click (recommended): press "Connect with Google" → pick your account and grant the drive.readonly permission → back in SemAgent a Google Picker opens and you select files or folders to index. No need to create your own OAuth app. Getting "Access blocked / redirect_uri_mismatch"? See troubleshooting.

With your own OAuth app (BYO) — Google Cloud Console step by step

Google moved the OAuth screens into the new Google Auth Platform (console.cloud.google.com/auth). The order is:

1. Select/create a project: use the project picker at the top, or New Project. Organization — with a personal Gmail account this is usually "No organization", which is fine; leave it. Google Workspace accounts have their org preselected.
2. Enable the Drive API: APIs & Services → Library → Google Drive API → Enable.
3. Consent screen / Branding: left menu Google Auth Platform → Branding → App name (e.g. SemAgent Data Source), User support email, Developer contact email → Save.
4. Audience: Google Auth Platform → Audience →
   • User type: choose External to connect personal Gmail or other Workspace accounts. (Choose Internal only for your own Workspace org — no consent screen needed.)
   • Publishing status: you can leave it in Testing; if so, ADD the Google account you'll connect to Test users (otherwise you get "Access blocked: app is being tested"). To open it to everyone use Publish app (the sensitive drive.readonly scope requires verification; Testing is enough for a test).
5. Scopes — Data Access: Google Auth Platform → Data Access → Add or remove scopes → add https://www.googleapis.com/auth/drive.readonly (read-only) via the list or "Manually add scopes" → Save. (drive.readonly is a restricted/sensitive scope — fine in Testing mode.)
6. Create an OAuth client: Google Auth Platform → Clients → Create client →
   • Application type: Web application.
   • Authorized redirect URIs → Add URI: https://semagent.ai/api/connectors/oauth/google/callback (and https://developers.google.com/oauthplayground if you'll use the Playground).
   • Authorized JavaScript origins: leave empty (server-side flow).
   • Create → save the returned Client ID and Client secret.
7. Connect in the panel (one-click — recommended): Data Sources → Google Drive → the "Connect with your own OAuth app" panel → enter Client ID + Client secret and press "Save & Connect". SemAgent runs the consent flow with YOUR app and mints the refresh_token for you — no manual token minting. (Your app can stay in Testing mode; remember to add yourself as a Test user.)
8. Alternative (manual refresh_token): if you prefer, mint one via the OAuth Playground: top-right gear → "Use your own OAuth credentials" → enter Client ID/Secret → left list Drive API v3 → drive.readonly → Authorize APIs → Exchange authorization code for tokens → paste the refresh_token into the panel's Refresh token + Client ID + Client secret fields (add the Playground to your redirect URIs). Optional Folder ID (the .../folders/<ID> from a Drive URL) limits to one folder.

OneDrive

Recommended — one click with your own app: register an Azure app with the steps below, enter Client ID + Client secret in the panel and press "Save & Connect". Seeing "OAuth not configured for this provider"? The central Microsoft OAuth isn't set up — that's expected; enter your own app's credentials (avoiding central verification / CASA is exactly the point).

With your own app (BYO) — Azure App registration step by step

1. ⚠️ Do NOT create a directory — you don't need one. Personal Microsoft/Outlook accounts can register the app without creating a directory. Trying to create one at portal.azure.com/#create/Microsoft.AzureActiveDirectory usually gives 401 "You don't have access" on personal accounts — skip that step. When you open portal.azure.com you're already in an auto-created "home" directory (a GUID-like directory shows top-right).
2. Register the app directly: type "App registrations" in the top search bar (or Microsoft Entra ID → App registrations) → + New registration → name it. Supported account types: ⚠️ choose "Accounts in any organizational directory (Multitenant) and personal Microsoft accounts" (required for personal OneDrive). (Ignore any "not contained within any directory" warning — the app still works.) Only if App registration itself says "no access", get a free real tenant via the Microsoft 365 Developer Program ("Join now" → xxxxx.onmicrosoft.com, you're Global Admin there) and register it in that tenant.
3. Redirect URI (Web): https://semagent.ai/api/connectors/oauth/microsoft/callback → Register.
4. API permissions → Add a permission → Microsoft Graph → Delegated: add Files.Read.All + offline_access. (Personal accounts don't need "Grant admin consent"; work/school directories may.)
5. Certificates & secrets → New client secret → copy the value. Note the Application (client) ID and (for a single-tenant app) the Directory (tenant) ID from Overview.
6. Connect in the panel (one-click — recommended): Data Sources → OneDrive → the "Connect with your own OAuth app" panel → enter Client ID + Client secret; if your app is single-tenant (your directory only), put your directory id in Azure Directory (Tenant) ID (leave common for multi-tenant/personal) → "Save & Connect". SemAgent runs the consent flow with your app. Optional Folder path limits to a subfolder. Text files (txt, md, csv, json, html) are indexed. (Alternative: mint a refresh_token manually and paste it into Refresh token + Client ID + Client secret.)

OneNote

Uses the same Azure app as OneDrive; only the permissions differ:

1. Reuse the same App registration (or make a new one; same redirect URI: .../oauth/microsoft/callback).
2. Add Microsoft Graph Delegated permissions Notes.Read.All + offline_access.
3. Data Sources → OneNote → the "Connect with your own OAuth app" panel → enter Client ID + Client secret (and Azure Directory/Tenant ID if single-tenant) and press "Save & Connect" (or paste a Refresh token manually). Notebook pages are converted to text and indexed.

Notion

Two ways: an Integration token (easiest, recommended) or one-click OAuth. Both go into the same panel field.

With an Integration token — step by step:

1. notion.so/profile/integrations (or Settings → Connections → Develop or manage integrations) → New integration → choose Internal and create. (The "Connections → Access token" or "Personal access tokens" on app.notion.com also give a valid API token — any of them works.)
2. Copy the Internal Integration Token (starts with secret_… or ntn_…).
3. Share the page: open the page/database you want indexed in Notion → top-right ••• → Connections → Connect to → [your integration]. ⚠️ Pages you don't share are INVISIBLE to the API — the connection can read "ok" yet return 0 docs.
4. Paste the token into Integration token in the panel; to target a single database set the Database ID from the URL → Sync.

Dropbox

Connect one-click with your own Dropbox OAuth app — none of the Microsoft directory pain applies here.

1. dropbox.com/developers/apps → Create app → Scoped access + Full Dropbox (or "App folder" to scope to one folder).
2. Permissions tab: check files.metadata.read + files.content.read + account_info.read and Submit.
3. Settings tab → OAuth 2 → Redirect URIs → add the panel's Redirect URI (https://semagent.ai/api/connectors/oauth/dropbox/callback). Copy the App key and App secret from the same page.
4. SemAgent → Data Sources → Dropbox → the "Connect with your own OAuth app" panel → put the App key into Client ID and the App secret into Client secret → "Save & Connect".
5. Optional: to index a single folder set Folder path to /Folder (empty = whole Dropbox). Text, PDF and Office (docx/xlsx/pptx) files are converted to text and indexed.

Zendesk

No OAuth app needed — an API token is enough (like Notion). By default Help Center articles are indexed; that's the most valuable source for a support bot.

1. In Zendesk open Admin Center → Apps and integrations → APIs → Zendesk API.
2. Enable Token access → Add API token → copy the token (shown once).
3. SemAgent → Data Sources → Zendesk: Subdomain (the acme of acme.zendesk.com), your admin email and the API token → Save & connect.
4. Optional Content type: articles (default) · tickets · both. Use both to also index support tickets (subject + description).

Troubleshooting

Google: "Access blocked / redirect_uri_mismatch"

• redirect_uri_mismatch (Error 400): your OAuth app's Authorized redirect URIs list does not contain https://semagent.ai/api/connectors/oauth/google/callback exactly. Add it (no trailing slash, https not http). This error is account-independent — you get it whatever account you pick; fix the URI first.
• "Access blocked: app is being tested": your Audience → Publishing status is Testing and the Google account you're connecting isn't in Test users. Add it, or Publish the app.

Microsoft: "AADSTS50058 / AADSTS50020 / 401 — interaction required, account does not exist in tenant"

• ⚠️ AADSTS50058 "Interaction required / cookies were not sent" (most common): this is a cookie/session problem, not permissions. It almost always comes from an InPrivate/Incognito window or strict tracking prevention (third-party cookies blocked). Fix: leave InPrivate, open a NORMAL window; in Edge set Settings → Cookies and site permissions → Tracking prevention → "Balanced" (not Strict) or allow cookies for [*.]microsoftonline.com + [*.]azure.com; sign in fully at portal.azure.com (complete the flow, don't click "Ignore"). Most reliable: use the M365 Developer Program tenant below.
• This happens when your personal (live.com/Gmail-based) account tries to open an Azure app that isn't yours (e.g. the Azure Portal's own app). Fix: don't open an existing app; create your own via portal.azure.com → App registrations → New registration.
• "You don't have access" (401) when creating a directory: don't try to create a directory at #create/Microsoft.AzureActiveDirectory — personal accounts get 401 there and don't need it. Register the app directly via App registrations → New registration with account type "Multitenant + personal Microsoft accounts" (works with no directory). Leave Azure Directory (Tenant) ID = common in the SemAgent panel.
• If App registration itself says "no access": get a free real tenant via the Microsoft 365 Developer Program ("Join now" → xxxxx.onmicrosoft.com, you're Global Admin) and register there. Still common in the panel (account type is multitenant+personal).