lupin.Open console
App connections

Resolve app authentication setup before starting OAuth

Distinguish authentication blueprints, provider credentials and customer consent when an integration is unavailable.

Lupin editorialAI-assisted3 min read

Separate the reusable blueprint from the account

A Composio auth config describes a toolkit’s authentication method, scopes and application credentials. A connected account is a particular owner’s authorization under that blueprint. Lupin needs both layers, but they have different administrators and lifecycles. An account owner cannot repair missing OAuth client credentials merely by trying the hosted link again. Likewise, a valid operator blueprint does not grant permission to read every user’s data. Keep setup readiness and owner consent as separate states so an agent can explain what remains to be done without asking for passwords or tokens.

Check the enabled Lupin catalog

Inspect GET /v0/connections/catalog with include_unavailable=true and the intended app search. connections_not_configured indicates that provider, durable storage or catalog readiness is incomplete; unsupported_app means the requested app is outside the enabled set. Those conditions are different from a provider rejecting an owner’s consent. Record the exact code and app identifier. Do not work around an unavailable toolkit by sending arbitrary app names or exposing the operator’s auth-config ID in a client request. The backend derives its provider configuration from the controlled catalog.

Identify the missing operator dependency

Operator configuration includes the Composio project API key, durable storage and a configured HTTPS console return origin. Small installations can use COMPOSIO_AUTH_CONFIGS, while the durable catalog supports larger inventories. Some managed OAuth blueprints can be provisioned; custom OAuth apps that need client credentials remain explicitly unavailable until supplied. Other schemes may collect a user API key through hosted connection setup. The catalog must never invent those credentials. Check the provider’s current requirements and the app’s configured scopes through the normal operator workflow before offering it as ready.

Handle provisioning uncertainty with its checkpoint

Lupin’s operator provisioner requires explicit write enablement and writes a checkpoint before creating provider configuration. If interrupted, preserve that checkpoint and recover uncertain creations from inventory rather than creating the same blueprint blindly. This behavior is separate from an end user’s hosted OAuth attempt and should stay out of their normal task flow. An operator incident should identify the missing blueprint or uncertain creation privately. Deleting catalog rows to hide the error can remove the evidence needed to reconcile the provider’s actual state.

Retest with safe discovery before owner authorization

After the operator resolves setup, repeat the read-only catalog search and verify that the app appears with the expected readiness. Then let the owner start one deliberate hosted authorization attempt with a retained operation key. Do not claim that a catalog update proves OAuth consent or tool execution has succeeded. A sound completion record contains the ready app identifier, the intended account owner and the next authorization step. It leaves provider credentials private and avoids consuming connection capacity during repeated readiness checks that should have been simple reads.

Distinguish two similar support reports

An owner seeing unsupported_app needs the enabled catalog reviewed. An owner reaching hosted consent but being denied by the provider needs the provider grant or administrative policy reviewed. Keep both reports tied to their actual phase. Repeating OAuth cannot enable an absent blueprint, and editing a catalog cannot grant the owner’s provider permissions.

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.

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

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore connections Register an agent