Connections API

A connection is a credential or tool a run can use — a Gmail account, a GitHub token, a remote MCP server, an OAuth provider. Provision them without the dashboard.

Direct: token & MCP connections

# Store an API key/secret (encrypted in Vault)
curl https://api.openhelm.ai/v1/connections \
  -H "Authorization: Bearer oh_live_..." -H "Content-Type: application/json" \
  -d '{ "name": "GitHub PAT", "type": "token", "secret": "ghp_...", "env_var_name": "GITHUB_TOKEN" }'

# Register a remote HTTP/SSE MCP server (headers may use ${SECRET})
curl https://api.openhelm.ai/v1/connections \
  -H "Authorization: Bearer oh_live_..." -H "Content-Type: application/json" \
  -d '{ "name": "Acme MCP", "type": "mcp", "url": "https://acme.example/mcp",
        "transport": "http", "headers": { "Authorization": "Bearer ${SECRET}" }, "secret": "..." }'

Scope a connection to one project with project_id, or omit it to make it available to all the account's runs. The stored secret is write-only — it is never returned by GET /v1/connections.

Hosted link: OAuth providers

Providers that need a browser (Google, Notion, LinkedIn…) can't be created from a raw key. Mint a short-lived link instead:

curl https://api.openhelm.ai/v1/connections/links \
  -H "Authorization: Bearer oh_live_..." -H "Content-Type: application/json" \
  -d '{ "provider": "google" }'
# → { "url": "https://app.openhelm.ai/connections?add=google&grant=…", "expires_at": "…" }

Open the URL (signed in to the account that owns the key), complete authorisation, then poll GET /v1/connections until it shows auth_status: "authenticated".

When a run needs a connection that isn't there

The run fails with failure_reason: "auth_required" — OpenHelm tells you what's missing rather than guessing. Set up the connection and re-run.