Connectors and integrations

Connectors let your agents read from and write to your real tools (email, calendar, storage, chat and CRM) via OAuth or API key. The connection flow, per-tenant encryption and the endpoints are identical across every plan from First. The only exceptions are HubSpot, Pipedrive and Salesforce, exclusive to Pro and above. The rest of the difference between plans is in the departmental agents, the Amadeus orchestrator, the STU quota and support.

How connectors work

Each connector declares a connection flow (connectFlow) that determines how credentials are obtained. There are three types:

• oauth: the user authorizes access from the provider’s own login screen. Shara never sees the password; it receives an access token (and, when applicable, a refresh token) with the permissions the user consented to.
• api-key: you paste a key generated in the service’s panel. The key is encrypted before being persisted and is tied only to your tenant.

Once connected, the agent that needs the tool detects the active integration and adds it to its capabilities automatically. Each connector publishes a set of native tools (concrete actions like “send email” or “create event”) that agents can invoke.

OAuth connector catalog

Connectors that authenticate via OAuth (user consent at the provider). The Native tools column shows the tool names each connector exposes to the agents; Connect via shows the route that actually starts the connection and Scope shows who connects it.

Company or “My accounts”. Each person’s mail, calendar and files (Google: Gmail, Calendar and Drive; Microsoft: Outlook, Calendar and OneDrive) are connected in the profile, under My accounts, and the agents use the account of whoever asks them for something. Slack and Teams connect as a company and also as a personal account. GitHub is personal. The other connectors are connected once by the company, for the whole team.

Connector	Slug	Category	Native tools	Connect via	Scope
Gmail	me-gmail	Communication	send_email, list_inbox, search_mail	POST /me/personal-integrations/:slug/connect	Personal (“My accounts”)
Google Calendar	me-google-calendar	Productivity	create_event, list_events, check_availability	POST /me/personal-integrations/:slug/connect	Personal (“My accounts”)
Google Drive	me-google-drive	Storage	list_files, upload_file, download_file	POST /me/personal-integrations/:slug/connect	Personal (“My accounts”)
Outlook Mail	me-outlook	Communication	send_mail, list_inbox	POST /me/personal-integrations/:slug/connect	Personal (“My accounts”)
Microsoft Calendar	me-outlook-calendar	Productivity	create_event, list_events	POST /me/personal-integrations/:slug/connect	Personal (“My accounts”)
Microsoft Teams	microsoft-teams	Communication	send_message, list_channels, list_chats, search_messages	POST /mcp/oauth/start · POST /me/personal-integrations/:slug/connect	Company and personal
OneDrive	me-onedrive	Storage	list_files, download_file	POST /me/personal-integrations/:slug/connect	Personal (“My accounts”)
Slack	slack	Communication	send_message, list_channels, search_messages	POST /mcp/oauth/start · POST /me/personal-integrations/:slug/connect	Company and personal
GitHub	me-github	Development	repositories, issues and pull requests	POST /me/personal-integrations/:slug/connect	Personal (“My accounts”)
HubSpot (Pro and above)	hubspot	CRM and sales	sync_to_hubspot, fetch_hubspot_deal, import_hubspot_contacts	GET /v1/oauth/hubspot/start	Company
Pipedrive (Pro and above)	pipedrive	CRM and sales	sync_to_pipedrive, fetch_pipedrive_deal, import_pipedrive_contacts	GET /v1/oauth/pipedrive/start	Company
Notion	notion	Productivity	notion_query_database, notion_create_page, notion_append_block	POST /v1/integrations/notion/connect	Company
Calendly	calendly	Productivity	calendly_list_event_types, calendly_list_scheduled_events, calendly_create_invitation	POST /v1/integrations/calendly/connect	Company
Dropbox	dropbox	Storage	dropbox_list_files, dropbox_download_file, dropbox_upload_file	POST /v1/integrations/dropbox/connect	Company
Salesforce (Pro and above; coming soon)	salesforce	CRM and sales	contact and company import; CRM tools	GET /v1/oauth/salesforce/start?slug=salesforce	Company
Confluence	confluence	Documentation	read:pages, write:pages (pages)	GET /v1/oauth/confluence/start	Company
Holded	(none)	CRM and ERP	create_client_in_holded, issue_invoice, send_invoice, sync_stripe_customer_to_holded, fetch_invoice	API key: POST /integrations/holded/connect (no OAuth)	Company

POST /mcp/oauth/start only serves the Google, Microsoft and Slack connectors; any other catalog name answers 501 provider_not_configured. Calendly and Dropbox only start if the provider’s credentials are configured on the API; otherwise the start fails with unknown_provider.

This catalog keeps growing. In the meantime, a system without a dedicated connector can already integrate through the MCP gateway, the Server Agent or the Desktop Agent (below).

API key connector catalog

Connectors that don’t use OAuth. The key or secret is always per tenant and is encrypted with the same secure store as the OAuth tokens.

Connector	Slug	Flow	Category
Resend	resend	api-key	Transactional email
Mixpanel	mixpanel	api-key	Analytics
Segment	segment	api-key	Analytics
Coda	coda	api-key (the account’s API token)	Documentation
Zapier	zapier	outgoing webhook: you paste your Zap’s “Catch Hook” URL (hooks.zapier.com only)	Automation

Universal connectors

On top of the catalog, every plan from First has mechanisms to connect systems that don’t have a specific connector:

• Desktop Agent: an installable app for Windows, macOS and Linux that exposes your local apps (spreadsheets, accounting software, proprietary ERP) as team tools.
• Server Agent: an agent resident on your server to expose internal services to the agents.
• MCP gateway: Model Context Protocol for two-way integrations with your own tools.

Desktop Agent and Server Agent actions outside the allowlist require human approval before executing. Read What Shara is.

OAuth permission table by connector

The Default preset column is the set of scopes Shara requests when you don’t specify any when starting the connection. For the connectors served by POST /mcp/oauth/start (Microsoft Teams and Slack), the Available scopes are the same set: you can request a subset to keep to the minimum privilege, and any scope outside the connector’s declared ones is rejected with 400 unknown_scopes, and an empty list with 400 empty_scopes. Where a service is also connected per person (personal accounts, POST /me/personal-integrations/:slug/connect), the table says so.

Google: Gmail, Calendar, Drive

Personal account only (Profile → My accounts): each person connects their own Google account and the agents use the account of whoever asks them. Personal accounts (POST /me/personal-integrations/:slug/connect, optional scopes override in the body):

Service	Slug	Default preset
Gmail	me-gmail	https://www.googleapis.com/auth/gmail.readonly + https://www.googleapis.com/auth/gmail.compose + https://www.googleapis.com/auth/gmail.send + https://www.googleapis.com/auth/userinfo.email
Google Calendar	me-google-calendar	https://www.googleapis.com/auth/calendar.readonly + https://www.googleapis.com/auth/calendar.events + https://www.googleapis.com/auth/userinfo.email
Google Drive	me-google-drive	https://www.googleapis.com/auth/drive + https://www.googleapis.com/auth/userinfo.email

userinfo.email is requested in personal connections to identify which account was connected. Google asks for these permissions on its own consent screen; whether a given scope requires verification of the app before it can be enabled for external accounts is decided by Google.

Microsoft 365 / Entra ID: Outlook, Calendar, Teams, OneDrive

Every Microsoft flow always adds offline_access (to issue a refresh token), and the company manifests also declare User.Read (basic identity). Token refresh rotates the refresh token on every renewal; Shara handles this transparently.

Company connection (POST /mcp/oauth/start), Teams only: each person’s mail, calendar and files go in My accounts.

Service	Default preset	Available scopes
Microsoft Teams	Chat.ReadWrite + ChannelMessage.Send + Channel.ReadBasic.All + Team.ReadBasic.All + offline_access + User.Read	the same six

Personal accounts (POST /me/personal-integrations/:slug/connect):

Service	Slug	Default preset
Outlook	me-outlook	Mail.Send + Mail.ReadWrite + offline_access + openid + User.Read
Outlook Calendar	me-outlook-calendar	Calendars.ReadWrite + offline_access + openid + User.Read
Microsoft Teams	me-teams	Chat.ReadWrite + ChannelMessage.Send + Team.ReadBasic.All + offline_access + openid + User.Read
OneDrive	me-onedrive	Files.ReadWrite + offline_access + openid + User.Read

Whether a Microsoft scope needs consent from the client tenant’s administrator depends on that tenant’s Microsoft Entra configuration, not on Shara.

Slack

Company connection (POST /mcp/oauth/start). Shara requests bot scopes and, in addition, one user scope (search:read) so it can search messages: Slack does not let a bot token search. Connections made before it was added need reconnecting to search.

Type	Default preset	Available scopes
Bot	chat:write + channels:read + users:read	the same three
User	search:read	the same one

Personal account (me-slack, POST /me/personal-integrations/:slug/connect): chat:write + channels:history + im:history + identity.basic + identity.email.

GitHub

Personal account only (me-github, Profile → My accounts). Scopes: read:user + user:email + repo (GitHub has no read-only scope for private repositories). The agents read repositories, issues and pull requests with the account of whoever asks them.

CRM and ERP: HubSpot, Pipedrive, Salesforce and Holded

HubSpot, Pipedrive and Salesforce are exclusive to Pro and above. Each has its own start route, which takes no scope parameter: it always requests the preset below.

CRM / ERP	Route	Scopes requested
HubSpot	GET /v1/oauth/hubspot/start	oauth + crm.objects.contacts.read + crm.objects.contacts.write + crm.objects.deals.read + crm.objects.deals.write + crm.objects.companies.read + crm.objects.companies.write + crm.schemas.deals.read
Pipedrive	GET /v1/oauth/pipedrive/start	base + deals:full + contacts:full + search:read + users:read
Salesforce	GET /v1/oauth/salesforce/start?slug=salesforce	api + refresh_token
Holded	POST /integrations/holded/connect	No scopes: API key per tenant, validated against Holded and encrypted per tenant like every other credential.

Other OAuth connectors

Connected with POST /v1/integrations/:slug/connect, which uses these scopes unless the body sends its own scopes.

Connector	Default preset	Scope notes
Notion	(empty)	Doesn’t use scopes; the user picks the workspace and pages during their own consent.
Calendly	default
Dropbox	files.metadata.read + files.content.read + files.content.write + account_info.read

The connector catalog keeps growing. If the system you use doesn’t appear yet, the MCP gateway, the Server Agent or the Desktop Agent can connect it until it has a dedicated connector.

Step-by-step connection flow

For a client or external developer, the public integration contract is made up of the status query, an endpoint to start the connection and the provider’s callback. All of them need the session of a signed-in administrator (Authorization: Bearer <session token>); they do not accept an API key. The full journey is:

1. The client queries the status: GET /v1/integrations returns each connector served by that endpoint with its connectFlow, its status (disconnected, connected, error or refreshing) and the scopesGranted for your tenant.
2. The client starts the connection. There are two routes depending on the connector:
   • Google, Microsoft and Slack connectors of the MCP catalog (for example gmail, outlook-mail, slack): POST /mcp/oauth/start with { "mcpServerName": "<name>", "scopes": [...] } (scopes is optional) returns { authUrl, state }.
   • Connectors served by /v1/integrations (for example notion, resend; HubSpot and Holded use their own routes, see the tables above): POST /v1/integrations/:slug/connect. Depending on the connectFlow, for oauth it returns { kind: "oauth", authUrl, state }; for api-key it receives the key, encrypts it and returns { kind: "connected", integration }.
3. The user opens authUrl and authorizes at the provider. After consenting, the provider redirects to Shara’s public callback with a code and the state.
4. Shara validates the state, exchanges the code for the tokens, encrypts them and persists them tied to your tenant. The integration moves to connected status.
5. From there, any agent that needs that connector uses it automatically. Tokens are never returned to the client.

The status of the connectors is queried like this:

# List the connectors served by /v1/integrations and their status for your tenant
curl -s https://api.sharasaas.com/v1/integrations \
  -H "Authorization: Bearer $SHARA_SESSION_TOKEN"

The response describes each connector and its status:

{
  "integrations": [
    {
      "slug": "notion",
      "displayName": "Notion",
      "category": "productivity",
      "connectFlow": "oauth",
      "status": "disconnected",
      "scopesGranted": [],
      "lastHealthCheckAt": null,
      "lastError": null,
      "metadata": {}
    },
    {
      "slug": "resend",
      "displayName": "Resend",
      "category": "productivity",
      "connectFlow": "api-key",
      "status": "connected",
      "scopesGranted": [],
      "lastHealthCheckAt": "2026-06-16T09:30:00.000Z",
      "lastError": null,
      "metadata": {}
    }
  ]
}

To start an OAuth connection requesting a subset of scopes (minimum privilege), use the MCP route. Scopes are written exactly as the connector declares them; for Google, the full URL:

# Connect Gmail in read-only mode (subset of the preset)
curl -s -X POST https://api.sharasaas.com/mcp/oauth/start \
  -H "Authorization: Bearer $SHARA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "mcpServerName": "gmail", "scopes": ["https://www.googleapis.com/auth/gmail.readonly"] }'

The response returns the authorization URL and the single-use state:

{
  "authUrl": "https://accounts.google.com/o/oauth2/auth?client_id=...&state=...",
  "state": "9f3c1a7e-...-single-use"
}

Starting a connection also keeps the scopes you had already granted for the same provider, so connecting a second service doesn’t switch off the first. For api-key connectors, POST /v1/integrations/:slug/connect receives the key in the body and encrypts it before persisting it:

# Connect an api-key service
curl -s -X POST https://api.sharasaas.com/v1/integrations/resend/connect \
  -H "Authorization: Bearer $SHARA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "re_live_..." }'

Security guarantees of the OAuth flow

The connection flow builds in several protections by design, applied uniformly across every provider:

• PKCE on every provider. Every connection generates a code_verifier and its code_challenge, even for confidential clients. This protects the code exchange against interception.
• Single-use state (delete-on-read). The state is removed from the store the instant it’s read, before validating its expiry. Reusing the same state fails with 400 state_mismatch. TTL of 10 minutes.
• Authority tied to the token. Starting the connection requires an authenticated JWT; identity and tenantId are derived from the token, never from the query or the body. The callback doesn’t need a JWT: its authority is the validated state, tied to the tenant at start.
• Tokens encrypted before persisting. Access and refresh tokens are encrypted with authenticated encryption in a secure store, with the cryptographic material isolated per tenant, and never returned to the client.
• Scope validation against the manifest. On POST /mcp/oauth/start, requested scopes must be a subset of the declared ones; otherwise, 400 unknown_scopes (or 400 empty_scopes if the list is empty). POST /v1/integrations/:slug/connect does not validate scopes.
• Redacted provider errors. Error messages from the provider’s SDK are redacted before being logged or returned, to avoid leaking sensitive data.
• Automatic refresh. A periodic process renews tokens close to expiry. If the provider revokes access, the integration stops being used until it is reconnected.

Configuration best practices

• Request the minimum scope needed. On the connectors served by POST /mcp/oauth/start you can request a subset of the default preset (for example, in Teams, only Team.ReadBasic.All and Channel.ReadBasic.All plus offline_access if the agent only needs to read). Less scope means less attack surface and less verification friction.
• Register the exact redirect_uri in the provider’s console: it must match the public API callback character for character.
• Google: whether a scope requires app verification before it can be enabled for external accounts is decided by Google; check it before exposing the connection to external accounts.
• Microsoft: administrator consent depends on the client tenant’s Entra configuration. The refresh token rotates on every renewal.
• Slack: the company connection requests bot scopes and the user scope search:read (to search messages).
• CRM (HubSpot, Pipedrive and Salesforce): the start route always requests the full preset above; review it before authorizing.
• API key: the key or secret is always per tenant, never shared, and is encrypted with the same secure store as the OAuth tokens.

Missing your tool?

If you use a system that doesn’t have a native connector yet, it can almost always be integrated via the MCP gateway or the Server Agent. Tell us your case at integrations@aiginer.com and we’ll consider adding it.