Integrations

Also for this capability: API · CLI · SDKs

How your org connects third-party accounts like Slack, and revokes them.

Specification

An integration is a connection to a provider the platform does not own — Slack, GitHub, Google, Stripe — held on behalf of a tenant, with the credential in custody and the connection state in one registry. hanzoai/cloud apps/integrations is that registry, and /v1/integrations is its address.

The capability has two audiences over the one store: the org plane, where an admin connects a provider for the whole org, and the user plane, where a person links their own accounts. HIP-0126 fixed the vocabulary and HIP-1065 specifies the user plane's custody rules; this HIP is the capability declaration — the store, the target address, the operations, and what the surface refuses.

Motivation

Provider connections were the platform's most duplicated concern: each consumer that needed a token — automations, channels, marketing — was one bad refactor away from its own OAuth path and its own secret row. One registry with one custody exit is what makes "is this org connected to X" a fact askable in one place, and a token something no peer ever stores.

Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.

§1 The store

The capability owns one store: the integrations SQLite database (apps/integrations/store.go:73, sqlpool.Open("integrations", dir)). One row per (org, provider, owner); tenancy is the org column, which is part of the primary key. Rows hold non-secret state only. Credentials live solely in the key store (HIP-0027), sealed under a path built from the tenant — org connections under the org, user connectors under the (org, user) pair (apps/integrations/integrations.go:1564). A row MUST NOT carry a secret and a custody failure MUST NOT leave a row behind.

§2 The address

Every route answers under /v1/integrations: the provider lifecycle (/{provider}, /{provider}/connect, /callback, /verify, /disconnect), the provider-specific doors (Slack, GitHub, Discord, Teams, Telegram, GitLab, OpenRouter), and the user plane at /v1/integrations/connectors. Today the user plane is served at a second root, /v1/connectors; that pair is carried by cloud's openapi/misfiled.txt:34 and closes by fold — one store, so per HIP-0139 §7.1 there is no boundary to split on. The generated clients re-point on regeneration; the installed CLI's interactive device and PKCE flows (cli/src/commands/product/generated.rs:794) hard-code the old root and a flow in flight when the fold lands polls a dead path, so the fold MUST ship in a CLI release that re-points them.

§3 Operations, typed and declared

The connectors plane is typed end to end (apps/integrations/connectors.go:55): list, providers, token read, device start/poll, credential intake, refresh, delete. The org plane's OAuth callbacks, link flows and provider webhooks are declared with prose beside the route (openapi.Describe, apps/integrations/integrations.go) because none can be a value: a callback answers a redirect the provider dictates, a link flow renders HTML, and a webhook's authentication is the provider's signature over the raw body — the signature check IS the authentication and it fails closed (apps/integrations/integrations.go:602).

§4 Tenancy

A request becomes a tenant through the validated principal's org (HIP-0026, principal.Org); a client-forged org header is refused. Org-plane writes that change what the whole org is connected to require the caller's own-org admin bit (principal.IsOrgAdmin — never SuperAdmin, apps/integrations/integrations.go:1096). User-plane rows are keyed by the (org, user) pair per HIP-1065, with no admin gate. Provider webhooks arrive with no principal and are admitted by signature alone.

§5 Metering, events, telemetry, stage

The capability is free, said in those words: plugin/integrations/main.go:29 declares Price: cloud.Free and no spend table names it. It publishes no events on the bus. Peers do not read its store: whether an org is connected is asked over the internal plane (apps/integrations/connection_rpc.go:30), and token handoff to in-process consumers goes through the same seam, never the address. It emits nothing to observability beyond the request span every route gets. Stage: ga.

§6 Upstream

The capability derives from none. Every provider client is hand-rolled Go over net/http against the provider's public API; no vendor SDK is imported and no third-party project is forked, embedded or mirrored.

Rationale

The alternative to one registry with two planes is two capabilities — org integrations and user connectors — which reads well until the store is drawn: both would open the same database, the defect HIP-0106 names. The two audiences differ in key, not in kind, so they are one capability whose address says which plane a route is on.

Security Considerations

The wrong implementation hands an attacker credentials. The exposures, each closed in code: a secret in a row or log (custody is the only holder, one operation returns a token); a cross-tenant read (org in the primary key, the (org, user) pair as the user-plane row key); a forged provider webhook (signature verification, fail closed); a concurrent refresh destroying the credential it refreshes (single-flight with adoption, apps/integrations/refresh.go:20); and custody-path smuggling (the path is validated before use).

Four surfaces

Quickstart

export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/integrations, operation get_integrations:

hanzo integrations list

import { Configuration, IntegrationsApi } from 'hanzoai';

const api = new IntegrationsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getIntegrations();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import IntegrationsApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = IntegrationsApi(client).get_integrations()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.IntegrationsAPI.GetIntegrations(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, integrations_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = integrations_api::get_integrations(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.IntegrationsApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new IntegrationsApi(client).getIntegrations();

curl https://api.hanzo.ai/v1/integrations \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_connectors"
         }
       }
     }'

Answers 200 with object — ok.

Endpoints

All Hanzo APIs · Interactive reference