External Service Integration Research Scratchpad

Last updated: 2026-05-05 Status: active scratchpad Owner: agent Scope: centralized external account connections for Tangle identity + downstream agent systems Gist: https://gist.github.com/shekohex/66e5a9abf1782d5d1f8234ca588fb2d8

TL;DR

One-line pitch

We should treat integrations as core platform infra: Tangle owns identity, delegation, policy, and audit; use Nango to accelerate connector auth; optionally expose it to agents through an Executor-style gateway.

Short version

No single open standard or product solves whole problem.
Best standards backbone is:
- OAuth 2.x + OIDC for account linking
- RFC 8693 token exchange for internal delegated access
Best architecture is layered:
- id.tangle.tools stays identity + consent anchor
- Tangle integration hub becomes system of record for connections, token vault, scopes, policy, audit, delegation
- Nango sits underneath as near-term connector/OAuth/token substrate
- Executor-style gateway can sit on top for agent UX, MCP, tool discovery
Do not give raw provider refresh tokens to sandboxes or bots.
Do not use workflow tools like n8n as source of truth.
Do not rely on one vendor as long-term architecture.

Recommendation

Approve layered strategy:

Tangle hub as core system of record.
Nango for fast bootstrap of connector auth/token mechanics.
Executor-style gateway optional for agent-facing access.

Why this wins

one user connects once, many Tangle systems benefit
centralized audit and policy
least-privilege delegated access
preserves provider-native depth
faster than building every connector from zero
avoids hard vendor lock-in at core platform boundary

Summary

Current best answer: there is no single open standard that gives us both multi-provider account linking and unified cross-provider business APIs for Gmail, Calendar, Docs, Twitter/X, Slack, GitHub, etc. Market leaders solve this with layered architecture, not one spec.

Canonical working copies now exist in both places:

local repo scratchpad: .planning/external-service-integration-research.md
public gist: https://gist.github.com/shekohex/66e5a9abf1782d5d1f8234ca588fb2d8

Recommended path:

Keep id.tangle.tools as user identity + consent anchor.
Add separate integration control plane that owns provider connections, OAuth apps, refresh tokens, scopes, audits, policy, and internal delegation.
Do not hand raw third-party refresh tokens to sandboxes, bots, or future products.
Let internal runtimes request short-lived delegated access through token exchange or brokered execution.
Expose two access modes:
- provider-native passthrough for full capability
- normalized high-value domain APIs for common actions like mail, calendar, files, contacts, messaging
Use open standards where they exist:
- OAuth 2.x + OIDC for auth and consent
- RFC 8693 token exchange for internal delegation
- RFC 9396 rich authorization requests for fine-grained consent where supported
- RFC 9449 DPoP or sender-constrained tokens for stronger token replay resistance
- SCIM for provisioning, not runtime data access
- MCP as agent tool exposure layer, not as connection/auth substrate
Short-term fastest route: self-host Nango or similar connector platform for OAuth/token lifecycle, put Tangle-specific policy + delegation in front of it.
Long-term durable route: Tangle-owned connection hub with pluggable provider adapters and optional use of Nango/open-source components under hood.
Provider onboarding cost is not only technical. Google sensitive/restricted scopes can trigger verification and annual security review, so scope minimization must be part of system design from day one.
executor.sh-style gateway is useful, but at different layer: strong as agent-facing execution/catalog/policy gateway; not enough by itself as centralized identity-owned connection control plane for all future Tangle systems.
Comparison result: build-only wins on control and fit but is slowest; Nango-under-hub is best near-term connector substrate; Executor-on-top is best agent gateway layer. Best stack is hub + Nango-underneath + optional Executor-style top layer.
Full matrix now included. No single product checks every box standalone. Best answer remains layered composition, not single-product adoption.

Google-like design pattern: central token broker plus short-lived delegated credentials. Not token fanout. Refresh tokens stay in hardened control plane. Downstream systems receive audience-bound, time-bound, least-privilege credentials or invoke brokered actions.

Problem Statement

Need one place where user connects external accounts once, then any approved Tangle runtime can use those connections safely.

Target consumers:

sandbox
trading bots
future agents
future backend products
workflow/automation subsystems

Required properties:

one user identity across products
one consent surface per provider/account connection
centralized token storage and refresh
policy controls over which internal system can use which connection
auditable delegated use on behalf of user
future-proof interface for agent tools and non-agent backends
no fake unification that blocks provider-specific features

Current Repo Context

Current repo docs explicitly say there is no partner OAuth lane today and that cross-site OAuth is internal-product-only. Relevant references:

docs/external-integration.md
docs/specs/platform-auth-product-interactions.md
.memory/flows/platform-id-auth-product-contract.md

Implication: this proposal is net-new platform surface, not extension of current public integration contract.

Core Finding

There are really 4 separate concerns. Many products blur them, which creates bad architecture decisions.

User identity
Third-party account linking and consent
Token brokerage / delegated execution for internal systems
Tool and API presentation to agents and products

One standard does not cover all 4.

Standards Landscape

1. OAuth 2.x + OIDC

This is non-negotiable base layer for external account linking.

What it solves:

user consent
access tokens
refresh tokens
delegated API access
identity claims when provider supports OIDC

Why it matters here:

Google Workspace, GitHub, Slack, Microsoft, many modern providers use OAuth 2.0/OIDC
internal Tangle identity platform can also use OIDC semantics for its own consumers

Limits:

does not unify provider APIs
does not say how our sandbox gets access safely after user linked account once

2. RFC 8693 OAuth 2.0 Token Exchange

Best-fit standard for internal delegation.

What it solves:

one internal actor exchanges its token for another short-lived token
preserve actor/subject semantics for audit
audience/scope downscoping

Why it matters here:

sandbox can exchange user/session/runtime token for narrow integration-hub token
trading bot can get time-bound access without receiving provider refresh token
closest standards-based answer to “central identity connected once, many internal systems consume later”

This is closest thing to Google-style design. Google Cloud STS implements token exchange for delegated access patterns.

3. RFC 9396 Rich Authorization Requests

Useful if we want fine-grained consent objects beyond loose scope strings.

Reality:

not universally supported by SaaS providers
more useful for our internal auth server to encode specific requested actions/resources

4. RFC 9449 DPoP

Optional hardening layer.

What it solves:

sender-constrains tokens
reduces replay value if access token leaks

Fit:

strong fit for browser/mobile/public client patterns
maybe overkill for first version but good for roadmap

5. SCIM

Important, but different problem.

What it solves:

user/group provisioning into external apps

What it does not solve:

runtime delegated data access for agents
Gmail send/search
Calendar CRUD
Docs access

Conclusion: relevant for enterprise provisioning later, not core architecture for agent integrations.

6. MCP

Relevant at tool interface layer, not core connection layer.

What it solves:

standard way to expose tools/resources/prompts to AI systems
standard auth expectations for AI tool consumers

What it does not solve:

provider token storage
refresh lifecycle
unified SaaS semantics
cross-product internal delegation model

Conclusion: expose integration hub capabilities via MCP after core broker exists.

7. Domain-Specific Protocols

Open standards exist for some domains, but coverage is partial.

IMAP/SMTP: email
CalDAV: calendars
CardDAV: contacts
JMAP: modern JSON protocol spanning mail/contacts/calendars and emerging file support

Value:

can reduce adapter count for providers that support them

Limits:

major SaaS providers still push proprietary APIs for richer features
does not cover social networks, docs, chat, issue trackers, CRMs, etc.

Direct Answer: Is There One Open Standard For Multi-Provider Unified Access?

No, not in the broad sense needed here.

Best available answer:

use OAuth/OIDC for connection and consent
use token exchange for internal delegation
optionally use MCP for agent-facing tools
optionally use JMAP/CalDAV/CardDAV/IMAP where provider coverage exists
build or buy connector/adaptor layer for actual provider API normalization

Zapier, n8n, Pipedream, Merge, Apideck, Composio, Unified.to, Nango: all effectively do provider-specific connector work plus some normalization. They are not built on one universal API standard adopted by providers.

Architecture Options

Option A. Identity Broker Only

Examples:

Keycloak
Authentik
Zitadel

What it gives:

social login / identity brokering
OIDC/SAML federation
session management
user/account linking

Why not enough:

usually optimized for login federation, not ongoing API token brokerage for hundreds of SaaS connectors
weak story for normalized provider actions
you still need connection metadata, refresh lifecycle, scopes, provider adapters, execution policies

Best use:

identity anchor for users and internal clients
maybe useful if replacing or extending current platform identity stack

Verdict:

necessary-ish component class
insufficient as full solution

Option B. Build Tangle-Owned Integration Control Plane

What it includes:

provider registry
OAuth app registry
connection records per user/workspace/provider/account
encrypted refresh token vault
token refresh workers
permission policy engine
internal token exchange
audit/event log
provider-native passthrough API
normalized domain APIs
MCP/OpenAPI exposure

Why strong:

exact fit for Tangle product model
future systems all consume same internal contract
avoids vendor lock-in on core identity and delegation
can encode Tangle-specific policy like sandbox-scoped approvals, execution budgets, tenant rules, audit chain

Why hard:

connector maintenance is expensive
provider auth edge cases never end
Google/Microsoft/Slack/GitHub are manageable; long tail is painful
compliance and secret handling burden lands on us

Verdict:

strongest long-term architecture
risky if built from zero without connector leverage

Option C. Use Open-Source Connector Platform Under Tangle Broker

Examples:

Nango

Pattern:

Tangle identity platform remains source of truth for user/app auth
Tangle integration hub fronts Nango for OAuth/token refresh/provider connectivity
internal systems never talk to Nango directly
Tangle layer adds policy, audit, delegation, normalized contracts, MCP/OpenAPI surface

Why strong:

fastest path to working OAuth connector estate
lowers cost of provider auth maintenance
still preserves Tangle-owned platform contract
can migrate provider-by-provider later if needed

Why weak:

another dependency/control plane to operate
some normalized models may not match Tangle domain needs
need careful abstraction so Nango does not leak into product architecture

Verdict:

best near-term starting point

Option D. Commercial Unified API / Embedded Integration SaaS

Examples:

Apideck
Merge
Pipedream Connect
Unified.to
Composio for AI-centric tooling

Why strong:

fastest time to market
broad provider support
embedded connect UIs
provider auth handled for us

Why weak:

expensive at scale
vendor lock-in risk on schemas and connection ids
some products focus on business SaaS categories, not broad agent workloads
may be awkward for sandbox/bot runtime delegation model
may not satisfy future compliance/data residency requirements

Verdict:

good benchmark and fallback
weak as foundational control plane for Tangle if strategic goal is shared infra asset

Option E. Use Workflow Automation Platform As Core Integration Layer

Examples:

n8n
Zapier
Pipedream workflows

Why attractive:

lots of connectors
easy demos
agent-triggered automations

Why wrong as core architecture:

workflow engines are execution plane, not identity/control plane
poor fit as centralized permission broker for all future systems
normalized API surface is secondary or absent
long-running product backend use cases become awkward

Verdict:

use later as optional execution consumer of connection hub
do not make this system of record

Option F. Use Executor-Style Agent Gateway

Reference:

executor.sh
GitHub: RhysSullivan/executor

What it is:

unified execution environment for AI agents
typed tool catalog across OpenAPI, GraphQL, MCP, Google Discovery, and custom plugins
shared auth + policies across multiple agent clients
MCP server bridge so one catalog can be reused by Cursor, Claude Code, OpenCode, custom agents

What it does well:

agent experience
tool discovery by intent
one place to expose many APIs to many agents
policy prompts like auto-approve reads / pause on writes
works as gateway in front of existing APIs and tool sources

Why it is interesting for Tangle:

very close to agent-consumption layer we need
could become front door for sandbox agents to access tools
could sit on top of Tangle integration hub and expose hub APIs as typed tools
useful for internal prototyping before full productized hub exists

Why it is not sufficient alone:

our problem is broader than agent tool access
we need identity-platform-owned connection lifecycle for all future systems, including non-agent backends
executor is positioned primarily as agent integration layer, not canonical user connection vault for product infrastructure
local-first design and team cloud roadmap do not automatically satisfy centralized multi-product identity, delegated auth, enterprise consent, or product-backend consumption needs
likely still needs separate source of truth for user-linked external accounts, grants, audits, org policies, and token brokerage

Best fit:

northbound gateway / agent facade on top of Tangle integration hub
not southbound source of truth for connections

Verdict:

yes, we can use this style
no, it should not replace core integration control plane

Recommendation

Recommend hybrid of Option B + Option C.

Recommendation In One Line

Build Tangle-owned integration hub and delegation model; use open-source connector platform like Nango underneath for provider OAuth/token mechanics until enough scale justifies replacing pieces.

Optional top layer: use an Executor-style gateway for agent-facing discovery, policy, and MCP exposure above the hub.

Why This Wins

Preserves strategic control over identity, delegation, audit, policy.
Avoids raw refresh-token fanout into sandboxes and bots.
Gives all future products one internal contract.
Delivers faster than building connectors from zero.
Keeps exit path from vendor/open-source dependency.
Leaves room for an Executor-style agent gateway without making agent tooling concerns drive core identity architecture.

Proposed Target Architecture

flowchart LR
  U[User] --> ID[id.tangle.tools]
  ID --> HUB[Integration Hub]
  HUB --> VAULT[Encrypted Token Vault]
  HUB --> REG[Provider Registry]
  HUB --> AUDIT[Audit Log]
  HUB --> NORM[Normalized APIs]
  HUB --> PASS[Provider Passthrough APIs]
  HUB --> MCP[MCP Server]
  HUB --> OAS[OpenAPI]

  HUB --> G[Google Workspace]
  HUB --> X[Twitter X]
  HUB --> GH[GitHub]
  HUB --> SL[Slack]

  SB[Sandbox] -->|token exchange| HUB
  TB[Trading Bot] -->|token exchange| HUB
  WF[Workflow System] -->|token exchange| HUB
  APP[Future Product] -->|token exchange| HUB

Control Plane Responsibilities

provider app config
OAuth redirect/callback handling
connection lifecycle
token encryption and rotation
scope management
revocation handling
rate-limit and quota policy
audit trail
capability metadata

Data Plane Responsibilities

invoke provider-native operations
execute normalized operations
stream results back to callers
redact/store minimal data unless caching explicitly needed

Optional Agent Gateway Layer

If we adopt Executor-style gateway pattern, place it above hub.

Tangle integration hub remains system of record for connections and delegation.
Executor-style layer indexes hub APIs plus selected direct sources into one agent catalog.
Agents talk to gateway.
Non-agent backends can call hub directly.

This keeps agent ergonomics and platform control separate.

Internal Auth Model

User logs into Tangle identity.
User links Google/Twitter/etc through integration hub.
Hub stores refresh token encrypted.
Sandbox or bot presents Tangle-issued token.
Hub performs token exchange and issues short-lived internal capability token or executes action directly.
Hub fetches/refreshes provider access token on demand.
Audit log records user, actor system, tool, scopes, provider, object ids, outcome.

Important Rule

Never mount or copy provider refresh tokens into runtime sandboxes unless absolutely unavoidable. Prefer brokered calls or ephemeral, audience-bound access.

API Surface Recommendation

Need 2 layers, not 1.

Layer 1. Provider-Native Passthrough

Examples:

google.gmail.messages.send
google.calendar.events.insert
github.issues.create
x.tweets.create

Why keep it:

preserves full provider feature set
avoids lowest-common-denominator trap
good for advanced agents and product teams

Layer 2. Normalized Domain APIs

Examples:

mail.send
mail.search
calendar.list-events
calendar.create-event
files.list
files.read
contacts.search
chat.post-message

Why add it:

faster agent/tool building
easier policy and evaluation
less provider-specific prompt engineering

Design rule:

normalize only top-value primitives used across 3+ providers
always keep escape hatch to provider-native APIs

Google-Specific Notes

Google Workspace should be treated as reference provider because it exercises most hard problems:

OAuth consent
offline refresh tokens
granular scopes
multiple products under one provider family
admin and domain-wide delegation edge cases

Recommended Google stance:

Default to user-consented OAuth with offline access for end-user data.
Use domain-wide delegation only for enterprise admin-approved org scenarios, not as default consumer flow.
Separate user-linked connections from organization-managed connections in data model.
Store granted scopes per connection and enforce them at execution time.
Minimize requested scopes aggressively. Sensitive/restricted scopes can trigger Google verification and, for some restricted scopes, annual third-party security assessment.

Provider Variability Warning

Do not assume all providers behave like clean OAuth 2.0 APIs.

Some providers support OAuth 2.0 + refresh tokens cleanly.
Some have partial OAuth 2.0 support, inconsistent scopes, or custom token behavior.
Some keep important features behind proprietary endpoints, app review, elevated access, or enterprise tiers.

Architecture implication:

keep provider adapter boundary explicit
model provider capabilities per connector
do not promise full normalization for every provider
launch with a curated provider set first

Data Model Sketch

Core entities:

principal: user or organization in Tangle
consumer: sandbox, bot, workflow, product backend
provider: google, github, slack, x, microsoft
connection: linked external account
grant: scopes + consent metadata + policy bindings
capability: operations permitted through normalized/provider-native APIs
delegation: runtime-specific short-lived approval/use record
execution_log: auditable action result

Useful connection fields:

provider
provider account id
principal id
connection type: user | org | shared-service
scopes granted
refresh token reference
status
created at
last refreshed at
last used at
revoked at

Security Requirements

Baseline:

encrypt refresh tokens at rest with KMS/HSM-backed envelope encryption
never expose refresh tokens to browser clients
prefer brokered execution over token distribution
least-privilege scopes
per-consumer allowlists
per-action audit
approval model for high-risk actions like email send, tweet post, funds movement

Stronger roadmap:

DPoP or sender-constrained internal tokens
policy-as-code for action approval
anomaly detection on provider usage
revocation propagation
dual control for org-wide shared connections

Open-Source / Vendor Landscape

Identity / Federation

Keycloak: strong open-source IAM, identity brokering, social login. Good if we need mature federation control plane.
Authentik: strong open-source IdP and federation UX. Good operational fit for modern teams.
Zitadel: modern auth platform with strong OAuth/OIDC posture.

Role in proposal:

identity layer only

Connector / OAuth Hub

Nango: strongest open-source fit found so far for product integrations, OAuth handling, token refresh, connection management, optional unified API.

Role in proposal:

best bootstrap candidate under Tangle-owned hub

Workflow / Automation

n8n: strong open-source workflow execution and connector catalog. Good downstream consumer, not source of truth.

Role in proposal:

optional execution layer fed by integration hub

Commercial Benchmarks

Apideck: broad unified API / connector platform
Merge: strong in business SaaS unified categories
Pipedream Connect: embedded auth + workflow ecosystem
Composio: AI/agent-centric connector layer with MCP story

Role in proposal:

benchmark product design and pricing pressure
fallback if build timeline too slow

Comparison Table

Legend

✓ = strong fit / directly satisfies
~ = partial fit / can help but not complete
✗ = weak fit / not intended for this requirement

Unless row explicitly says under Tangle hub or on top of Tangle hub, scoring assumes product used as the primary solution, not hidden behind major custom wrapper.

Full Option Inventory

Option	Category	Open source / self-host	Primary value	Best role in Tangle architecture	Why not enough alone
Build-only Tangle hub	custom platform	yes	exact-fit control plane	long-term core system of record	slowest path, highest connector maintenance burden
Nango under Tangle hub	connector substrate	yes	OAuth + token lifecycle + provider connectivity	southbound connector/auth substrate	still needs Tangle-owned delegation, policy, audit, and public contract
Executor-style gateway on top of Tangle hub	agent gateway	yes	agent tool catalog, MCP, policies, discovery	northbound agent facade	not source of truth for user connections or internal auth delegation
Keycloak	identity broker	yes	mature IAM, federation, social login	identity/federation layer	not product-integration control plane
Authentik	identity broker	yes	modern IdP, federation, UX	identity/federation layer	not product-integration control plane
Zitadel	identity broker	yes	modern auth, federation, brokering	identity/federation layer	not product-integration control plane
n8n	workflow automation	yes	large connector catalog + workflows	downstream workflow execution consumer	workflow engine, not canonical connection authority
Apideck	unified API / connector SaaS	no	broad connector abstraction	commercial benchmark or temporary acceleration	vendor contract becomes architecture quickly
Merge	unified API SaaS	no	polished normalized APIs in business SaaS categories	narrow commercial benchmark	category-limited, not broad agent infra foundation
Pipedream Connect	embedded integration SaaS	no	embedded auth + workflows + external accounts	commercial benchmark, maybe for faster embedded UX	workflow-centric, less ideal as central platform control plane
Composio	AI/agent integration platform	mixed	agent-centric connector + auth + MCP story	benchmark for agent-facing integrations	AI-first layer, weaker as canonical non-agent platform substrate

Quick Verdict

Option	Best role	Strengths	Weaknesses	Verdict
Build-only Tangle hub	core system of record	exact fit, full control, clean internal delegation, no platform lock-in	slowest path, highest connector maintenance cost	long-term target
Nango under Tangle hub	connector/OAuth substrate	fastest serious path, handles OAuth/token refresh/provider auth edge cases, self-hostable	extra dependency, connector abstraction may leak if not wrapped well	best near-term base
Executor-style gateway	agent-facing gateway	great MCP/catalog/policy UX, typed tools, shared access across many agents	not canonical connection vault, weaker fit for non-agent backends and identity-owned delegation	best top layer

Requirement Matrix

Requirements on x-axis, products/options on y-axis.

Product / Option	User IdP	Acct Link	Token Vault	Delegation	Policy/Audit	Prov API	Norm API	Agent UX	Backend API	Self Host	Fast Start	Ctrl
Build-only Tangle hub	✓	✓	✓	✓	✓	✓	✓	~	✓	✓	✗	✓
Nango under Tangle hub	~	✓	✓	~	~	✓	~	~	✓	✓	✓	~
Executor-style gateway on top of Tangle hub	✗	✗	~	✗	~	~	~	✓	~	✓	✓	~
Keycloak	✓	~	~	~	~	✗	✗	✗	~	✓	~	~
Authentik	✓	~	~	~	~	✗	✗	✗	~	✓	~	~
Zitadel	✓	~	~	~	~	✗	✗	✗	~	✓	~	~
n8n	✗	~	~	✗	~	~	✗	~	~	✓	✓	✗
Apideck	✗	✓	✓	✗	~	~	✓	~	✓	✗	✓	✗
Merge	✗	✓	✓	✗	~	✗	✓	✗	✓	✗	✓	✗
Pipedream Connect	✗	✓	✓	✗	~	~	✗	✓	~	✗	✓	✗
Composio	✗	✓	✓	✗	~	~	✗	✓	✗	~	✓	✗

Column notes:

User IdP: can anchor user identity/federation
Acct Link: can own user-linked third-party account connection flow
Token Vault: can store/refresh third-party credentials centrally
Delegation: can issue or enforce short-lived on-behalf-of internal access
Policy/Audit: can enforce usage policy and record auditable use
Prov API: preserves provider-native API depth
Norm API: offers normalized cross-provider API surface
Agent UX: strong agent-facing catalog/MCP/tool discovery/policy experience
Backend API: suitable for non-agent backend systems directly
Self Host: practical self-host/open deployment path
Fast Start: fast path to initial shipping
Ctrl: strategic control for Tangle long-term

Matrix Readout

Takeaways from matrix:

Identity brokers hit User IdP, but miss most integration-control-plane requirements.
Unified API vendors hit Acct Link and Token Vault, but usually miss Delegation, Ctrl, and often full Prov API depth.
Agent gateways hit Agent UX, but miss canonical connection ownership.
Workflow tools are useful consumers, not good roots of truth.
Only Build-only Tangle hub aims to satisfy almost every column, but it loses on Fast Start.
Best practical composition is still:
- Tangle hub for User IdP adjacent control plane, Delegation, Policy/Audit, Backend API, Ctrl
- Nango for Acct Link, Token Vault, initial Prov API acceleration
- Executor-style gateway for Agent UX

Capability Matrix

Capability	Build-only Tangle hub	Nango under Tangle hub	Executor-style gateway
User-linked external account source of truth	strong	medium if wrapped by Tangle, weak if used directly	weak
Refresh token vault + lifecycle	strong	strong	medium at best, not core value prop
Internal token exchange / delegated auth	strong	medium, should live in Tangle layer	weak
Non-agent backend consumption	strong	strong when fronted by Tangle APIs	medium
Agent ergonomics / MCP / tool discovery	medium unless separately built	medium	strong
Provider connector time-to-market	weak	strong	medium
Provider API normalization	strong but costly	medium to strong depending on connector coverage	weak to medium
Tangle-specific policy / audit model	strong	strong if kept in Tangle layer	medium
Strategic control	strong	medium to strong	medium
Long-tail provider maintenance burden	weak	medium	medium

Recommendation From Comparison

Use all 3 concepts, but at different layers.

Tangle-owned hub as control plane and system of record.
Nango as bootstrap substrate for connector auth/token mechanics.
Executor-style gateway as optional northbound layer for agents, MCP, tool discovery, and approval UX.

Do not invert stack.

Do not make Executor source of truth for all external account connections.
Do not expose Nango internals directly as long-term product contract.
Do not force non-agent backend consumers through agent-first gateway semantics when direct hub APIs are cleaner.

Decision Framework

Choose architecture based on 5 questions.

Do we want Tangle to own connection metadata and permissions as strategic platform asset?
Do we expect non-agent systems to use same connections heavily?
Do we need auditable on-behalf-of delegation across many internal runtimes?
Do we need provider-native depth beyond lowest-common-denominator unified APIs?
Do we need self-host / future compliance control?

If mostly yes, full vendor SaaS should not be core system.

Suggested Implementation Phases

Phase 0. Architecture Spike

pick 3 reference providers: Google Workspace, GitHub, Slack or X
prove user-linked connection flow
prove internal token exchange flow
prove brokered action from sandbox

Success criteria:

user connects Google once
sandbox can list calendar events without seeing refresh token
audit trail shows user + sandbox actor + action

Phase 1. Control Plane MVP

provider registry
connection table
encrypted token vault
callback handlers
token refresh job
internal auth + token exchange
provider-native actions for reference providers

Phase 2. Tooling Surface

OpenAPI for product backends
MCP server for agents
normalized domain APIs for mail/calendar/files

Phase 3. Governance

approvals
per-consumer policy
org/shared connections
admin reporting

Phase 4. Expansion

more providers
workflow engine integration
SCIM for enterprise provisioning
event/webhook ingestion

What We Should Actually Do

Concrete recommendation:

Do not try to find one standard that replaces connector work. It does not exist for this problem.
Adopt OAuth/OIDC + token exchange as standards backbone.
Create Tangle integration hub as first-class platform service beside identity.
Use Nango as initial connector/OAuth substrate unless strong reason against.
Keep provider refresh tokens inside hub only.
Give downstream systems short-lived delegated access or brokered actions.
Expose both provider-native and normalized APIs.
Treat MCP as one consumer-facing interface, not foundation.

Open Questions

Should org admins be able to create shared team connections distinct from personal connections?
Should high-risk actions require runtime approval or pre-approved policy only?
Should some integrations be data-sync based instead of live API calls?
Do we want per-product isolated OAuth apps or central shared OAuth apps per provider?
Do we need customer-managed keys or region-specific token vaulting?

References

Standards

OAuth 2.0 Token Exchange RFC 8693: https://datatracker.ietf.org/doc/html/rfc8693
OAuth 2.0 Rich Authorization Requests RFC 9396: https://datatracker.ietf.org/doc/html/rfc9396
OAuth 2.0 DPoP RFC 9449: https://datatracker.ietf.org/doc/html/rfc9449
SCIM Core Schema RFC 7643: https://datatracker.ietf.org/doc/html/rfc7643
SCIM Protocol RFC 7644: https://datatracker.ietf.org/doc/html/rfc7644
JMAP Core RFC 8620: https://datatracker.ietf.org/doc/html/rfc8620
JMAP Mail RFC 8621: https://datatracker.ietf.org/doc/html/rfc8621
JMAP Contacts RFC 9610: https://datatracker.ietf.org/doc/html/rfc9610

Official Product / Vendor Docs

Google OAuth 2.0 for web server apps: https://developers.google.com/identity/protocols/oauth2/web-server
Google Cloud Security Token Service: https://cloud.google.com/iam/docs/reference/sts/rest
Google Workspace domain-wide delegation best practices: https://support.google.com/a/answer/14437356
Model Context Protocol docs: https://modelcontextprotocol.io/
MCP authorization spec: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
Nango docs: https://docs.nango.dev/
Nango GitHub: https://github.com/NangoHQ/nango
Keycloak docs: https://www.keycloak.org/docs/latest/server_admin/#_identity_broker
Keycloak GitHub: https://github.com/keycloak/keycloak
Authentik docs: https://docs.goauthentik.io/
Authentik GitHub: https://github.com/goauthentik/authentik
n8n docs: https://docs.n8n.io/
Apideck docs: https://developers.apideck.com/
Merge docs: https://docs.merge.dev/
Pipedream Connect docs: https://pipedream.com/docs/connect/
Composio docs: https://docs.composio.dev/
Executor site: https://executor.sh/
Executor GitHub: https://github.com/RhysSullivan/executor

Repo References

docs/external-integration.md
docs/specs/platform-auth-product-interactions.md
.memory/flows/platform-id-auth-product-contract.md

shekohex/external-service-integration-research.md

External Service Integration Research Scratchpad

TL;DR

One-line pitch

Short version

Recommendation

Why this wins

Summary

Problem Statement

Current Repo Context

Core Finding

Standards Landscape

1. OAuth 2.x + OIDC

2. RFC 8693 OAuth 2.0 Token Exchange

3. RFC 9396 Rich Authorization Requests

4. RFC 9449 DPoP

5. SCIM

6. MCP

7. Domain-Specific Protocols

Direct Answer: Is There One Open Standard For Multi-Provider Unified Access?

Architecture Options

Option A. Identity Broker Only

Option B. Build Tangle-Owned Integration Control Plane

Option C. Use Open-Source Connector Platform Under Tangle Broker

Option D. Commercial Unified API / Embedded Integration SaaS

Option E. Use Workflow Automation Platform As Core Integration Layer

Option F. Use Executor-Style Agent Gateway

Recommendation

Recommendation In One Line

Why This Wins

Proposed Target Architecture

Control Plane Responsibilities

Data Plane Responsibilities

Optional Agent Gateway Layer

Internal Auth Model

Important Rule

API Surface Recommendation

Layer 1. Provider-Native Passthrough

Layer 2. Normalized Domain APIs

Google-Specific Notes

Provider Variability Warning

Data Model Sketch

Security Requirements

Open-Source / Vendor Landscape

Identity / Federation

Connector / OAuth Hub

Workflow / Automation

Commercial Benchmarks

Comparison Table

Legend

Full Option Inventory

Quick Verdict

Requirement Matrix

Matrix Readout

Capability Matrix

Recommendation From Comparison

Decision Framework

Suggested Implementation Phases

Phase 0. Architecture Spike

Phase 1. Control Plane MVP

Phase 2. Tooling Surface

Phase 3. Governance

Phase 4. Expansion

What We Should Actually Do

Open Questions

References

Standards

Official Product / Vendor Docs

Repo References