Authorization Flow

Toolcog uses on-demand authorization—AI requests access exactly when it needs it, with exactly the permissions required. No upfront configuration, no unnecessary scopes, just seamless authorization at the moment of need.

The On-Demand Flow

When AI tries to use an API that requires authentication:

This happens naturally in conversation. AI explains what it needs, you authorize, and work continues.

Why On-Demand Is Better

Minimal Scopes

Traditional integrations request broad permissions upfront: “Give me access to all your repos, all your issues, all your pull requests.”

Toolcog requests exactly what’s needed:

1. AI calls find_api to discover an operation
2. AI calls learn_api to understand the interface
3. AI calls call_api—but no credentials exist
4. AI requests authorization with exactly the scopes that operation needs

If you later ask AI to do something requiring additional scopes, it asks again. Your authorizations expand incrementally.

No Pre-Configuration

You don’t need to:

• Set up OAuth applications
• Configure API keys before you can use them
• Decide upfront which services you might need

Just start working. When AI needs access, it asks.

Explicit Consent

Every authorization is explicit. You see exactly what you’re authorizing:

• Which service (GitHub, Stripe, Notion)
• Which scopes (read repos, create issues, manage billing)
• Which catalog is requesting access

Nothing happens without your click.

The Authorization URL

When AI needs authorization, it provides a URL like:

https://toolcog.com/connect?owner={owner}&bridge={bridge}&scope={scope}

This URL contains:

• Owner — Who owns the bridge (user or org handle)
• Bridge — Which API or catalog
• Scope — What permissions are needed (optional)

Clicking this link starts the OAuth flow.

What Happens During Authorization

1. You click the link — Opens in your browser
2. You sign in to Toolcog — If not already signed in
3. You’re redirected to the service — GitHub, Google, etc.
4. You authorize Toolcog — Grant the requested permissions
5. You’re redirected back — Authorization complete
6. Your credentials are stored — Encrypted in your vault
7. You return to AI — It can now complete the operation

The whole process takes seconds.

Credential Storage

Your credentials are stored with four-tier encryption: session → derived key → vault key → encrypted credential. Even Toolcog cannot decrypt your credentials—the encryption keys are derived from secrets only you possess. See Zero-Knowledge Credential Protection for details.

Session-Scoped Access

Credentials are tied to your Toolcog session:

• Your MCP session — The AI client connected to Toolcog
• Your vault — Where your encrypted credentials live
• Your authorizations — Which services you’ve connected

When you authorize an MCP client from your browser, the client automatically shares your browser session’s vault. Sessions created independently (different devices, different browsers) have separate vaults by default, but can be merged later. See Vault Linking for details.

Multi-Service Workflows

Authorization works across services. If AI needs to:

1. Read from GitHub
2. Create in Notion
3. Send via Slack

Each service is authorized independently when needed. AI handles this naturally:

“To summarize your GitHub issues in Notion, I’ll need access to both. First, please authorize GitHub: [link]”

You authorize GitHub.

“Thanks! Now I need Notion access: [link]”

You authorize Notion.

“I’ve created the summary page in Notion with your latest issues.”

User Control

You’re always in control:

• View connections — See what you’ve authorized
• Revoke access — Remove authorization anytime
• Reconnect — Re-authorize if tokens expire
• Multiple accounts — Connect multiple accounts per service

See Manage Credentials for details.

Next Steps

• OAuth Services — Services that use OAuth
• API Keys — Services that use API keys
• Manage Credentials — View and manage authorizations