---
title: Basalt Connections & Automation Gateway
category: Integrations
icon: 🔌
sort_order: 21
slug: basalt-connections
canonical_url: https://basaltnotes.com/guides/basalt-connections
markdown_url: https://basaltnotes.com/guides/basalt-connections.md
---
# Basalt Connections & Automation Gateway

Basalt separates connection credentials, incoming context, proposed action, and execution. That boundary lets a small number of reusable bridges cover many services without giving an orchestrator silent authority over your knowledge or external accounts.

## What Is Native Today

- Google Calendar and Gmail plus Microsoft Calendar, Outlook mail, and OneDrive can be read through account connections with service-specific delegated scopes.
- Google Drive, Dropbox, and GitHub content operations use server-owned credentials, provider-specific target allowlists, capability checks, request quotas, and blocked redirects.
- Connected Calendar, mail, and file responses are bounded, metered, audited, marked as temporary, and never persisted by the account server. The user can explicitly capture an event, message, or file reference into local portable Markdown.
- Calendar and mail mutations are represented as connection-bound Forge proposals. They require workspace policy and an explicit role-aware review; there is no direct provider-write route or OAuth write scope.
- Hosted REST and MCP address only an explicit hosted vault mapping. They do not make a local-only browser vault remotely readable.
- Provider webhooks notify Basalt that connected data changed; they do not include provider credentials or directly mutate a vault.

These are implementation boundaries, not a claim that Linear, Jira, or every possible provider has a bespoke native connector or that approval alone can execute a provider write without a capability-specific executor.

## Why Zapier and n8n Come First

Zapier and n8n can authenticate with a Basalt developer token, import the OpenAPI 3.1 catalog, send events, and create Forge proposals. They remain the recommended force multipliers for Linear, Jira, and long-tail systems while usage reveals which connectors deserve dedicated OAuth, sync, and capability-policy work.

Both adapters use the same endpoints and contracts:

1. `POST /api/dev/automation/events` ingests a bounded, fingerprinted `BasaltEvent`.
2. `POST /api/dev/automation/proposals` stores a bounded `ActionProposal` with an explicit idempotency key, reversibility declaration, and execution budget.
3. `POST /api/dev/automation/process` lets an authenticated orchestrator wake due schedules and retry leases for that account.
4. The proposal stays in `proposed` state. There is no bridge execution endpoint.
5. A trigger or agent routes it through policy and Forge for review, audit, and supported undo.

## Microsoft account and ingestion paths

The native Microsoft account path uses authorization-code OAuth with PKCE, encrypted refresh-token custody, delegated `User.Read`, `Calendars.Read`, `Mail.Read`, and `Files.Read` scopes, bounded Microsoft Graph reads, explicit local capture, revocation from Basalt, and account-scoped audit events. Configure the exact callback `${APP_URL}/api/connections/oauth/microsoft/callback` in Microsoft Entra.

The separate `microsoft-graph` developer adapter still accepts normalized Calendar, Outlook mail, and OneDrive events from an authenticated bridge. That bridge remains ingestion-only; it does not carry or expose the user's native Microsoft OAuth credentials.

## Production closure gates

Code and fixture validation do not prove a production provider grant. Before closing the deployment checklist, configure both provider applications, complete any consent/publisher review, and live-test authorization, refresh, bounded read, explicit local capture, revocation, proposal creation, Forge approval/rejection, and audit visibility with disposable Google and Microsoft accounts. Provider writes remain proposal-only until a separately reviewed executor is introduced.

## Portable Contracts

Connection events and proposals use the same versioned shared contracts as tasks, trust records, Pulse, Strata, and future schedules. Correlation, causation, depth, fingerprints, entity references, approval policy, idempotency, reversibility, and budgets remain readable JSON rather than a proprietary workflow encoding.

The gateway is a durable foundation for broader connections; it does not claim that typed schemas for every external system are complete.