Connectors
Per-org app connectors (OAuth ingestion)
Per-org app connectors (OAuth ingestion)
| Base URL | https://api.hanzo.ai |
| Operations | 8 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
connectors
Forces a token rotation for a connected connector, ahead of the automatic rotation a token read would do inside the expiry window.
POST /v1/connectors/{id}/refresh
Forces a token rotation for a connected connector, ahead of the automatic rotation a token read would do inside the expiry window. Only providers that declare a Refresh support it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the connector id, provider + ":" + label ("openai:default") — the auth-profile-id shape. |
Hands the custodied access token to its owner — the ONE place custody exits.
GET /v1/connectors/{id}/token
Hands the custodied access token to its owner — the ONE place custody exits. The (org,user)-keyed row IS the same-user gate: another user's id is simply "no row" → 404. fresh() auto-rotates within the refreshSkew window; static providers degenerate to a plain kmsGet of Secrets[0]. Refresh tokens are NEVER returned — custody keeps the sink. The token is never logged.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the connector id, provider + ":" + label ("openai:default") — the auth-profile-id shape. |
Forgets a connector: every custodied secret, then the row.
DELETE /v1/connectors/{id}
Forgets a connector: every custodied secret, then the row. Idempotent — dropping a never-connected id still answers {disconnected:true} (disconnect() parity). No provider Revoke: none of the user-plane providers exposes a revoke endpoint.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the connector id, provider + ":" + label ("openai:default") — the auth-profile-id shape. |
Is the direct intake path: a customer-held token/setup-token (Verify) or an externally obtained OAuth bundle from the CLI's local PKCE (Adopt).
POST /v1/connectors/{provider}/credential
Is the direct intake path: a customer-held token/setup-token (Verify) or an externally obtained OAuth bundle from the CLI's local PKCE (Adopt). ALWAYS verify-before-store: a bad credential is refused and NOTHING is persisted (connectByCredential's fail-closed order).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Provider is the user-scoped provider's registry id, from the path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
accountId | string | — | AccountID scopes the credential where the provider's Verify needs one. |
label | string | — | Label names this connection; empty means "default". |
oauth | cloud_oauthBundleIn | — | OAuth is a bundle the CLI already obtained through its own local PKCE flow. |
provider | string | — | Provider is the user-scoped provider's registry id, from the path. |
token | string | — | Token is the customer-held credential for the Verify path. |
Advances a device sign-in.
POST /v1/connectors/{provider}/device/{flow}/poll
Advances a device sign-in. Terminal outcomes are DATA, not errors (verifyConn {active:false} discipline) — the status set is closed: pending|connected|denied|expired. pollSlow collapses to "pending" on the wire; the raised cadence rides interval.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Provider is the user-scoped provider's registry id, from the path. |
flow | path | string | yes | Flow is the id deviceStartOut returned. |
Begins a device sign-in and returns the code to show the user plus how to poll for completion.
POST /v1/connectors/{provider}/device
Begins a device sign-in and returns the code to show the user plus how to poll for completion. KMS readiness is checked NOW rather than dead-ending the user at poll-done (connect() parity), and the per-provider connector cap is checked before the provider is called. The provider's device code is persisted only in the encrypted grants table and is NEVER returned.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
provider | path | string | yes | Provider is the user-scoped provider's registry id, from the path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
label | string | — | Label names this connection so one user can hold several per provider ("work", "personal"). Empty means "default". |
provider | string | — | Provider is the user-scoped provider's registry id, from the path. |
Lists the user-scoped provider cards — the catalog of what a user can connect, and how.
GET /v1/connectors/providers
Lists the user-scoped provider cards — the catalog of what a user can connect, and how. Methods derive from capabilities (Device/Adopt/Verify — Mount asserts at least one), never from a parallel kind enum.
Lists the caller's OWN connectors across every provider — the set hanzo connector ls prints.
GET /v1/connectors
Lists the caller's OWN connectors across every provider — the set
hanzo connector ls prints. Rows are keyed (org,user), so this can never
surface another user's connector, and no secret is in the view.
How is this guide?