Authenticated Requests

Most useful things require authorization. Listing your GitHub repos. Creating a Stripe invoice. Checking your Cloudflare settings. This is where Toolcog’s on-demand authorization shines.

Try It

Ask Claude to do something that requires your credentials:

“List my GitHub repositories”

Here’s what happens:

1. Claude discovers the operation

Claude uses find_api to locate github/listRepositoriesForAuthenticatedUser.

2. Claude attempts to call it

Claude constructs the request and calls call_api. The system checks for GitHub credentials in your encrypted vault. Finding none, it sends the request without authentication.

3. GitHub returns 401 Unauthorized

{
  "status": 401,
  "statusText": "Unauthorized",
  "body": {
    "message": "Requires authentication"
  }
}

4. Claude recognizes the auth error and helps you

Instead of just failing, Claude provides a way forward:

“I need authorization to access your GitHub account. Click here to connect: [authorization link]”

5. You click the link

The link takes you to Toolcog’s connect flow:

  1. You see what’s being authorized (GitHub, repository access)
  2. You click “Authorize”
  3. GitHub asks you to grant permission
  4. You approve
  5. You’re redirected back

Your OAuth tokens are now encrypted in your vault. Toolcog never sees your GitHub password—just the access token GitHub issues, immediately encrypted with keys only you can access.

6. You ask Claude to try again

“Try that again”

This time, the system finds your GitHub credentials, decrypts them, applies them to the request, and GitHub returns your repositories.

That’s it. You just authorized a service in the flow of conversation, exactly when it was needed.

Why This Matters

Traditional integrations require upfront configuration. Go to settings, find the integrations page, locate GitHub, click connect, grant permissions, return to what you were doing. This interrupts your flow and requires granting broad access before you know what you’ll actually use.

Toolcog inverts this:

What Happened Under the Hood

When you authorized GitHub:

  1. OAuth flow initiated — Toolcog redirected you to GitHub’s authorization page using PKCE (proof key for code exchange) for security.

  2. You granted permission — GitHub asked if you want to grant Toolcog access to your repositories. You approved.

  3. Tokens exchanged — GitHub returned an authorization code. Toolcog exchanged it for an access token and refresh token.

  4. Credentials encrypted — The tokens were immediately encrypted using your vault’s encryption key—derived from secrets only you possess.

  5. Stored securely — Encrypted credentials were stored, associated with your account and the GitHub API.

When Claude retried:

  1. Credentials retrieved — The system fetched your encrypted GitHub credentials.
  2. Decrypted on-demand — Using your session key, credentials were decrypted just for this request.
  3. Applied to request — The access token was added to the HTTP request’s Authorization header.
  4. Request executed — GitHub validated the token and returned your repositories.
  5. Credentials discarded — The plaintext token was immediately discarded after use.

At no point did Claude see your credentials. The conversation contains your request and the response, but never the authentication details.

Multiple Services, Same Pattern

This pattern repeats for every service:

“Show my Stripe customers” → authorize Stripe → works

“Create a Slack message” → authorize Slack → works

“Check my Cloudflare DNS” → authorize Cloudflare → works

Each authorization happens on-demand. Each is scoped to what you’re actually doing. Each follows the same click-authorize-continue flow.

What If You Need More Access?

Sometimes you start with read access and later need write access. No problem—the same pattern applies:

“List my GitHub issues” → works (you already have read access)

“Create a GitHub issue titled ‘New feature request’” → needs write scope → click to authorize → works

The system detects when an operation requires scopes you haven’t granted and prompts you to authorize the additional access. Your existing authorization isn’t revoked; it’s expanded.

Next Steps