---
name: connect
description: "Reach a platform's API — Google Ads, Meta, X, LinkedIn, Analytics, Salesforce, Slack, GitHub and the rest — through Hanzo's own connector plane, so the credential is custodied and never written to disk. Use whenever a skill needs live data or write access to an outside service: 'connect my Google Ads', 'pull my Meta spend', 'post to LinkedIn', 'read Search Console', 'is my account connected', 'refresh the token', 'disconnect'. Every platform skill defers here rather than running an OAuth flow of its own."
---

# Connect

One way to reach an outside platform, for every skill that needs one.

## Why this exists

A platform skill written on its own tends to carry its own OAuth dance, its own
SDK install and its own credential file — `pip install <vendor>`, then a JSON
blob under `.agents/`. That is three problems at once: a long-lived secret in
plaintext on a disk somebody else can read, a token nobody can rotate, and as
many auth implementations as there are skills.

Hanzo already holds the connectors, in Go, per user. They are the one door.

- **The secret never leaves custody.** A credential is verified live, then
  sealed into KMS before any row is written. It appears in no row, no response
  and no log — the single exception is the token read below, which exists
  because a caller has to get one somehow.
- **A connector belongs to a person, not a workspace.** Every read and write is
  bound to `(org, user)`, so another user's connector id is simply not there.
- **Rotation is a request, not a migration.** One POST re-mints.

## The surface

Host is `api.hanzo.ai`. Send the signed-in user's bearer; send no org header —
the org comes from the token.

```
GET    /v1/integration/connectors                                 what this user has connected
GET    /v1/integration/connectors/providers                       what can be connected
GET    /v1/integration/connectors/{id}/token                      a usable access token
POST   /v1/integration/connectors/{provider}/device               begin a device sign-in
POST   /v1/integration/connectors/{provider}/device/{flow}/poll   wait for it to finish
POST   /v1/integration/connectors/{provider}/credential           hand over a token you already hold
POST   /v1/integration/connectors/{id}/refresh                    rotate now
DELETE /v1/integration/connectors/{id}                            forget it, and its secrets
```

A connector's **id is `provider:label`** — so one person can hold two Google Ads
accounts as `google_ads:work` and `google_ads:client`, and a skill that wants
"the" account should ask which when there is more than one.

## Two ways in, one plane behind them

The surface above is HTTP, and an agent with a shell can call it directly. It is
also projected as MCP tools at `https://api.hanzo.ai/v1/mcp`, so an agent with
the Hanzo MCP server attached can reach the same connectors as tools without
composing a request. Either is correct — they are the same routes, typed once in
Go and projected, so a tool and a curl cannot come to disagree about what a
connector is.

Prefer the tools where they are attached: an agent that has them gets argument
validation and does not have to hold a token in a shell variable.

## The flow a skill follows

```
1. GET /v1/integration/connectors
       └─ already there?  → step 3
2. POST /v1/integration/connectors/{provider}/device
       └─ show the user the code, then poll .../device/{flow}/poll until it settles
3. GET /v1/integration/connectors/{id}/token
4. call the platform with that token
       └─ 401 → POST .../{id}/refresh once, then retry
```

Ask for a token when you are about to use it, not at the start of a session: it
is short-lived by design, and holding one across a long conversation is how a
skill ends up refreshing something it never needed.

## Providers

These are the ids the plane actually serves. Naming one it does not is a skill
that fails at the first call with nothing useful to say.

**Marketing and ads** — `google_ads`, `meta_ads`, `adroll`, `x`, `linkedin`,
`tiktok`, `pinterest`, `reddit`, `youtube`, `instagram`, `threads`, `facebook`

**Data and analytics** — `google_analytics`, `google_bigquery`, `google_cloud`,
`google`, `salesforce`

**Messaging** — `slack`, `discord`, `teams`, `telegram`, `whatsapp`, `twitch`

**Work** — `github`, `linear`, `microsoft`

`GET /v1/integration/connectors/providers` is the live answer and outranks this
list, which is a convenience and will age.

### What is not here

**Google Search Console has no provider.** A skill that needs it should say so
and stop, rather than reaching for a vendor SDK and a credentials file — that is
the arrangement this skill replaces. `google_analytics` and `google_bigquery`
answer many of the same questions and are connected.

## Rules

- **Never write a credential to disk.** No `.agents/*credentials*.json`, no
  `.env`, no config file. If a skill's instructions tell you to, they predate
  this plane and the token read above is what they wanted.
- **Never install a vendor SDK to authenticate.** The token is HTTP; so is every
  platform API it opens.
- **Never ask the user to paste a long-lived secret** when the provider supports
  the device flow. Where they already hold one, `POST .../credential` takes it
  and seals it.
- **A refusal is the platform's, and is worth repeating verbatim.** "Not
  connected" and "connected but the scope is missing" have different remedies.