OAuth Services

Most major APIs use OAuth for authorization—GitHub, Google, Stripe, Slack, and hundreds more. Toolcog handles OAuth flows automatically, so you just click a link and authorize.

Supported OAuth Services

Toolcog supports OAuth for any service that uses standard OAuth 2.0. Common examples:

If an API uses OAuth 2.0, Toolcog can handle it.

The Connect Flow

When AI needs OAuth authorization:

  1. AI provides a connect URL

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

  2. You click and authenticate — Sign in to the service if needed

  3. You grant permission — The service’s consent screen shows what access you’re granting

  4. Toolcog stores the token — Encrypted in your vault

  5. AI continues working — With the newly authorized access

PKCE Protection

All OAuth flows use PKCE (Proof Key for Code Exchange):

  1. Toolcog generates a cryptographic verifier
  2. Only that verifier can exchange the authorization code for tokens
  3. Even if the authorization code is intercepted, it’s useless without the verifier

This prevents authorization code interception attacks.

Token Storage

OAuth tokens are stored with envelope encryption: your session key derives a KEK, which unwraps your vault DEK, which decrypts the token. The token only exists in plaintext during the moment of API execution, then is immediately discarded.

Automatic Token Refresh

OAuth access tokens expire—typically in an hour. Toolcog handles this automatically:

  1. Token expires — The access token is no longer valid
  2. Refresh token used — Toolcog exchanges the refresh token for a new access token
  3. New token stored — The new access token is encrypted and saved
  4. Operation continues — No user interaction needed

You never see token refresh happening. It just works.

When Refresh Fails

Sometimes refresh tokens expire too (varies by service). When this happens:

  1. AI attempts the operation
  2. Refresh fails
  3. AI requests re-authorization
  4. You click the link and authorize again
  5. AI continues

Scope Management

OAuth scopes define what access you’re granting. Toolcog requests minimal scopes:

Incremental Scopes

If you first authorize read access, then later need write access:

  1. AI detects insufficient scopes
  2. AI requests additional authorization
  3. You authorize the new scopes
  4. Both read and write access now available

Your scopes expand only when you explicitly authorize.

Reconnecting

If your authorization becomes invalid (token expired, access revoked on the service side):

  1. AI attempts an operation
  2. Service returns 401/403
  3. AI provides a reconnect link
  4. You re-authorize
  5. AI continues with fresh credentials

Multiple Accounts

You can connect multiple accounts for the same service:

When AI needs to use a specific account, it uses the credentials associated with the current context.

Custom OAuth Apps

For enterprise or self-hosted scenarios, you can use your own OAuth applications:

  1. Create an OAuth app in the service’s developer console
  2. Create a custom realm in Toolcog with your client credentials
  3. Configure your catalog to use your realm

This gives you full control over the OAuth configuration.

Next Steps