Brokered HTTP and External APIs

Many packs exist to talk to external APIs. Worka supports that, but it does not treat those calls as ungoverned raw network access.

For pack execution, external HTTP should go through the brokered path.

Why brokered HTTP exists

The brokered path gives the platform control over:

• which domains are allowed
• which workspace connection backs the request
• how access tokens or metadata are injected
• where audit or policy enforcement can happen

That lets the pack describe what it needs without becoming its own secret manager or network policy engine.

How the pattern works

In the common pattern:

1. the pack declares outbound domains in aip.json
2. the pack declares a connection provider if one is needed
3. the tool constructs an HTTP request using broker-safe templates where appropriate
4. the broker resolves the active workspace connection
5. the request is sent with the right tokens or metadata applied

This keeps the pack portable across workspaces while still letting it make real API calls.

Connection-backed templates

The current template surface is intentionally narrow. It includes roots such as:

• {{connection.access_token}}
• {{connection.refresh_token}}
• {{connection.provider}}
• {{connection.metadata.<field>}}

Use those when the API call needs workspace-specific auth or context.

Normalize upstream responses inside the pack

The pack should turn provider-specific HTTP responses into clean structured tool results.

That means:

• the broker handles transport and controlled expansion
• the pack handles API normalization
• the workspace and view layer receive stable Worka-facing data

That separation keeps the rest of the workspace from becoming coupled to one vendor’s raw response shape.