Connections
How an external system is authorised once against your account and then selected by a workspace, and the four states a provider can be in.
A connection is an authorised link to one external system. It is held against your account, and a workspace then selects it. That two-step exists so a second workspace can use a provider you have already authorised without the credential being copied into a second place — the workspace record stores the selection, never the secret.
The four states, and why they are distinct
Providers are not uniformly “connected”. They reach Hawi by four different routes with genuinely different properties, and the product keeps them apart rather than flattening them into one green tick. A provider that is visible is not described as connected until its own flow has confirmed it.
| State | What it means | Who holds the secret | Example |
|---|---|---|---|
| Native OAuth | You authorise Hawi from inside the provider’s own consent screen. | Hawi, as a refreshable token. | A registry-approved OAuth provider |
| Encrypted seller credential | You supply a credential through a secure setup flow; it is encrypted at rest and never displayed again. | Hawi, encrypted. | A registry-approved credential provider |
| Verified connector | A connector definition that has been checked against the provider’s API before it is offered. | Varies by provider. | Only providers shown as available in the product |
| External setup | Configured outside Hawi and pointed at it, typically for systems with no public authorisation flow. | You, in the external system. | A provider configured in its own administration surface |
Read and write
A connection’s scope and an agent’s tool list are two different gates, and both apply. A workspace can hold a write-capable connection while every agent in it is restricted to reading through it. The narrower of the two wins, which means the safe way to introduce a new provider is to add it at the scope you eventually want and give the first agent read-only access to it.