Hanzo
OpenapiIntegrations

Acquires the org's credential for one provider.

Acquires the org's credential for one provider.

POST /v1/integrations/{provider}/connect

Addresshttps://api.hanzo.ai/v1/integrations/{provider}/connect
MethodPOST
Operationpost_integrations_by_provider_connect
AuthAuthorization: Bearer $HANZO_API_KEY

Acquires the org's credential for one provider. It has TWO paths and the REQUEST picks which: a "token" key in the body seals that credential directly (verify-before-store), and its absence begins the 3-legged OAuth flow — minting a single-use nonce plus an HMAC-signed state that binds this org to this provider, and answering with the provider's authorize URL for the caller to redirect to.

Fail-closed order, unchanged: no principal → 403; unknown provider → 404; an AdminOnly connector without the caller's own-org admin bit → 403; not configured → 503; KMS not ready → 503 (the flow WILL need to seal a token, so refuse now rather than dead-end at the callback).

Request

4 fields, body application/json (required).

FieldInTypeRequiredDescription
providerpathstringyesProvider is the connector's registry id, from the :provider path segment.
accountIdbodystringAccountID is the provider account the credential should be scoped to, for the providers whose Verify needs one (Cloudflare).
providerbodystringProvider is the connector's registry id, from the :provider path segment.
tokenbodystringToken is the customer's provider credential.

Response

StatusBodyMeaning
200connectOutok

200 body — 6 fields.

FieldInTypeAlwaysDescription
accountbodystringAccount is the account label the provider reported for the credential.
authorizeUrlbodystringAuthorizeURL is the provider consent URL to send the user to.
connectedbodybooleanConnected is true on the apikey path once the credential verified and sealed.
externalIdbodystringExternalID is the provider's account id for the credential.
providerbodystringProvider is the connector's registry id.
scopesbodystring[]Scopes are the permissions the credential carries.

Failure carries the platform error shape — see Errors.

Examples

hanzo integrations connect <provider>

Integrations API · All Hanzo APIs · Interactive reference

How is this guide?

On this page