Connectors and integrations

Connectors let your agents read from and write to your real tools (email, calendar, storage, chat and CRM) via OAuth, API key or webhook. The connection flow, per-tenant encryption and the endpoints are identical across every plan from First: the difference between plans is in the departmental agents, the Amadeus orchestrator, the STU quota and support, not in the connectors.

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.
• webhook: Shara provisions an endpoint and a secret per tenant to receive inbound events from external systems. The secret is never shared between tenants.

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 actions the connector exposes to the agents.

Connector	Slug	Category	Native tools
Gmail	gmail	Communication	send_email, list_inbox, search_mail
Google Calendar	google-calendar	Productivity	create_event, list_events, check_availability
Google Drive	google-drive	Storage	list_files, upload_file, download_file
Outlook Mail	outlook-mail	Communication	send_mail, list_inbox
Microsoft Calendar	microsoft-calendar	Productivity	create_event, list_events
Microsoft Teams	microsoft-teams	Communication	send_message, list_channels, list_chats, search_messages
OneDrive	onedrive	Storage	list_files, download_file
Slack	slack	Communication	send_message, list_channels, search_messages
HubSpot	hubspot	CRM and sales	get_contact, create_deal, log_activity
Pipedrive	pipedrive	CRM and sales	Deals, people and organizations
Notion	notion	Productivity	get_page, create_page, search
Holded	holded	CRM and ERP	Contacts, invoices and documents

This catalog keeps growing: we add new connectors every month. In addition, any system without a native connector can already integrate through the generic OAuth connector, HTTP webhooks, the MCP gateway or the Server Agent (below).

API key or webhook 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
Discord	discord	api-key	Communication
External automation	webhook	webhook	Receives events from your own automation tool

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.
• HTTP webhooks: receives events from any system and triggers flows in Shara.
• MCP gateway: Model Context Protocol for two-way integrations with your own tools.
• Generic OAuth connector: connects any OAuth 2.0 API even if it doesn’t yet have a dedicated connector in the catalog.

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. You can request a subset of the preset to keep to the minimum privilege: any scope outside the declared catalog is rejected with 400 unknown_scopes, and an empty list with 400 empty_scopes.

Google: Gmail, Calendar, Drive

Service	Default preset	Available scopes
Gmail	gmail.readonly + gmail.send + gmail.modify + userinfo.email	gmail.readonly, gmail.send, gmail.modify, userinfo.email, userinfo.profile
Google Calendar	calendar + calendar.events	calendar, calendar.events, calendar.readonly
Google Drive	drive.readonly + drive.metadata.readonly	drive, drive.readonly, drive.metadata.readonly, drive.file

Gmail, Calendar and Drive scopes are sensitive: the provider requires passing its app verification process before enabling them for external accounts. The drive.file scope (access only to files created by the app) is the least invasive option for Drive.

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

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

Service	Default preset	Available scopes
Outlook Mail	Mail.Read + Mail.Send + Mail.ReadWrite	Mail.Read, Mail.ReadWrite, Mail.Send
Microsoft Calendar	Calendars.ReadWrite	Calendars.Read, Calendars.ReadWrite
Microsoft Teams	Chat.ReadWrite + ChannelMessage.Send + Channel.ReadBasic.All + Team.ReadBasic.All	Chat.ReadWrite, ChannelMessage.Send, Channel.ReadBasic.All, Team.ReadBasic.All
OneDrive	Files.Read.All	Files.Read.All, Files.ReadWrite.All

Some Microsoft scopes (for example Files.ReadWrite.All) may require consent from the client tenant’s global administrator. This is anticipated in the enterprise onboarding.

Slack: bot token and user token

Slack distinguishes between the bot token (xoxb, the default mode) and the user token (xoxp, optional). By default Shara uses the bot token; the user token only activates if you need message search.

Type	Default preset	Additional scopes
Bot (xoxb)	chat:write + channels:read + users:read + app_mentions:read	chat:write.public, channels:history, groups:history, im:history, users:read.email, commands
User (xoxp, opt-in)	(none)	search:read (the only capability that requires the user token)

CRM and ERP: HubSpot, Pipedrive and Holded

CRM / ERP	Default preset	Available scopes
HubSpot	oauth + crm.objects.contacts.read/write + crm.objects.deals.read/write + crm.objects.companies.read/write + crm.schemas.deals.read	crm.schemas.contacts.read, crm.schemas.companies.read. The oauth scope is mandatory.
Pipedrive	base + deals:full + contacts:full + search:read + users:read	deals:read, contacts:read, activities:read, activities:full, admin
Holded	API key per tenant (contacts, invoices and documents)	Scope determined by the key configured in Holded; encrypted per tenant like every other credential.

CRMs use per-object/resource scopes. Grant write permission only on the objects where the agent will create or update records (for example, only deals if it only manages opportunities).

Other OAuth connectors

Connector	Default preset	Scope notes
Notion	(empty)	Doesn’t use scopes; the user picks the workspace and pages during their own consent.

We expand the connector catalog every month. If the system you use doesn’t appear yet, the generic OAuth connector covers any OAuth 2.0 API while we prepare the dedicated connector.

Step-by-step connection flow

For a client or external developer, the public integration contract is made up of two main endpoints and the provider’s callback. The full journey is:

1. The client queries the catalog and the connection status: GET /v1/integrations returns each connector with its connectFlow and whether it’s already connected for your tenant.
2. The client starts the connection: POST /v1/integrations/:slug/connect. Depending on the connectFlow, for oauth it returns { authUrl, state }; for api-key it receives the key and encrypts it; for webhook it provisions the per-tenant token.
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 catalog and connection status are queried like this:

# List the connector catalog and its status for your tenant
curl -s https://api.sharasaas.com/v1/integrations \
  -H "Authorization: Bearer $SHARA_TOKEN"

The response describes each connector and its availability:

{
  "integrations": [
    {
      "slug": "gmail",
      "name": "Gmail",
      "category": "communication",
      "connectFlow": "oauth",
      "connected": false,
      "scopes": ["gmail.readonly", "gmail.send", "gmail.modify", "userinfo.email"]
    },
    {
      "slug": "resend",
      "name": "Resend",
      "category": "productivity",
      "connectFlow": "api-key",
      "connected": true
    }
  ]
}

To start an OAuth connection requesting a subset of scopes (minimum privilege):

# Conectar Gmail solo en modo lectura (subconjunto del preset)
curl -s -X POST https://api.sharasaas.com/v1/integrations/gmail/connect \
  -H "Authorization: Bearer $SHARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": ["gmail.readonly", "userinfo.email"] }'

The response for an oauth flow returns the authorization URL and the single-use state:

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

For api-key connectors, the same endpoint receives the key in the body and encrypts it before persisting it:

# Conectar un servicio de tipo api-key
curl -s -X POST https://api.sharasaas.com/v1/integrations/resend/connect \
  -H "Authorization: Bearer $SHARA_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. Requested scopes must be a subset of the declared ones; otherwise, 400 unknown_scopes (or 400 empty_scopes if the list is empty).
• 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 moves to revoked status and stops being used until reconnected.

Configuration best practices

• Request the minimum scope needed. The default preset is broad for convenience. If your use case is read-only, request the subset (for example gmail.readonly without gmail.send, or Calendars.Read instead of Calendars.ReadWrite). 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: the Gmail, Calendar and Drive scopes are sensitive; prepare the app verification before exposing them to external accounts.
• Microsoft: some scopes require consent from the client tenant’s global administrator. The refresh token rotates on every renewal.
• Slack: use the bot token by default; only activate the user token if you need search:read.
• CRM (HubSpot / Pipedrive): grant write access only on the objects the agent will modify.
• API key and webhook: 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 webhooks, the MCP gateway or the Server Agent. Tell us your case at [email protected] and we’ll consider adding it.