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.

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.

Connectors that authenticate via OAuth (user consent at the provider). The Native tools column shows the actions the connector exposes to the agents.

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).

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.

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.

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.

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.

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.

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 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.

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).

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.

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.aiginer.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.aiginer.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.aiginer.com/v1/integrations/resend/connect \
  -H "Authorization: Bearer $SHARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "re_live_..." }'

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.

• 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.

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 integrations@aiginer.com and we’ll consider adding it.