Connect an app through its owner’s hosted authorization

Find an app your workspace can connect

Start with the configured catalog rather than a provider marketing inventory. GET /v0/connections/catalog accepts a search string and returns enabled app metadata without auth-config IDs or customer accounts. For a GitHub workflow, search github and inspect the exact app identifier in the response. An unavailable entry may need operator setup, and a no-auth entry represents a different capability. The presence of a toolkit in Composio does not mean that your Lupin workspace has a ready authentication configuration for it.

curl --fail-with-body --get "https://api.lupin.sh/v0/connections/catalog" \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  --data-urlencode "search=github" --data-urlencode "limit=25"

Use a workspace credential deliberately

Connection management requires an organization key. A project or inbox credential cannot administer a shared account, even if that project will later consume its results. Reading requires api_key_read; creating or reconnecting requires api_key_create. The restricted key returned by autonomous registration is not permission to authorize external applications or trigger paid effects. Have the workspace owner choose the account and approve connecting it. Do not request the owner’s provider password, access token or refresh token in an agent conversation.

Save the creation attempt before requesting a link

Create one stable operation key for the connection attempt and retain it across retries and page reloads. Send POST /v0/connections with the selected app and the saved Idempotency-Key header. The response includes an authorize_url; link creation itself does not establish that the account is active. Keep the returned connection ID alongside the app and your pending workflow. If the request times out or returns reconciliation_required, preserve the same key and operation ID. Starting another attempt with a fresh key can create another provider-side account.

curl --fail-with-body "https://api.lupin.sh/v0/connections"   -H "Authorization: Bearer $LUPIN_API_KEY"   -H "Idempotency-Key: $SAVED_CREATE_KEY"   -H "Content-Type: application/json"   --data '{"app":"github"}'

Let the owner finish hosted authorization

The owner opens the returned HTTPS authorization URL, checks the provider account and reviews the requested permissions before continuing. Composio owns the OAuth credential flow; Lupin keeps the durable account reference and presents sanitized status and scopes. This is a real provider dependency rather than a browser session imported into Lupin. For an organization account, the person authorizing may also need the provider’s administrative approval. A successful redirect back to the console is navigation and must not be interpreted as proof that access was granted.

Refresh authoritative account state

Read GET /v0/connections after the hosted flow. Lupin checks the provider account’s user_id against the workspace organization before showing account status. Accept the connection only when the returned status is active and the account matches the owner’s intended identity. A callback query string claiming ACTIVE cannot activate the registry. If the state remains pending, let the owner finish the same authorization or investigate the provider condition. Avoid repeatedly pressing connect because each new authorization attempt has its own lifecycle and potential usage consequences.

Discover tools before approving work

Once active, discover tools for the saved connection ID and inspect their real schemas. A GitHub connection does not grant an agent blanket permission to create issues, change repositories or send arbitrary requests. The Lupin consumer agent requests exact human approval for each app tool execution, including apparent reads. Save the discovered account revision and concrete tool version with that approval. A practical first milestone is a verified active connection plus a reviewed tool schema, leaving the actual external action for an explicitly authorized task.

Verify the intended account in the example

For a GitHub issue-triage workflow, the owner should confirm the engineering account after activation before the agent discovers issue tools. A personal account with the same display name is insufficient. The saved connection and reviewed account purpose prevent a later tool proposal from being routed by list order or a familiar alias.

Sources & verification

Reviewed against current checked-in Lupin routes, shared contracts and official provider references. No live calls, OAuth authorizations, app actions or purchases were performed.

• Lupin connections ↗Checked 2026-11-05
• Composio hosted account link API ↗Checked 2026-11-05
• Composio authenticating tools ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.