Data Sources

Admin Panel → Connections → 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 Admin Panel → Connections → Data Sources. A Connected Sources list sits on top, an Add a Connection section below.
2. Pick the source type to add (SQL · Google Drive · Dropbox · Notion · Zendesk).
3. Each source form has a How do I connect? button at the top — the source-specific steps and field help are available right in the panel too.
4. Fill the fields and press Save & connect. Each connected source's row has Content (browse indexed documents), Test (verify), Sync (re-pull), Webhook (copies the webhook URL), Edit and Delete.
5. Set how often it re-pulls with Sync interval (min) and full refreshes with Full re-sync.

Ways to connect (OAuth sources)

For the sources that connect with OAuth (Google Drive, Dropbox, Notion) the paths are:

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 SemAgent 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, ask [email protected] for the addresses to allow, then allow inbound connections from them 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, Dropbox 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; Google Drive and Dropbox): 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: in the Google Drive form's "Connect with your own OAuth app (recommended)" box, answer "What should we index?" and press "Save & Connect" → pick your account on Google's consent screen and grant access. If you leave Client ID and Client secret empty, SemAgent's central app is used (if your operator set it up); then you don't need to create your own OAuth app. In "Only the files I pick" mode, after connecting you select the files to index in the Google Picker that "Pick Files" on the card opens. 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.

Notion

Two ways: an Integration token (easiest, recommended) or one-click OAuth with the form's "Connect with Notion" button (if your operator set it up). 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.

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.