OAuth & Connected Apps

​

Overview

• One-click connect — authorize via the Connected Apps tab
• Auto-refresh — background daemon refreshes tokens before they expire
• On-demand refresh — if a token is expired when needed, it’s refreshed instantly
• BYOA — bring your own OAuth app credentials for white-label consent screens
• AES-256-GCM encryption — tokens encrypted at rest, decrypted only when needed

​

Supported Providers

​

Connecting an Account

​

Via Dashboard

1. Go to Dashboard → Credentials → Connected Apps
2. Find the provider you want to connect
3. Click Connect — you’ll be redirected to the provider’s authorization page
4. Authorize RunTools (or your BYOA app) to access your account
5. You’ll be redirected back with a Connected status

​

Via CLI

# Start OAuth flow (opens browser)
runtools oauth connect google

# List connected accounts
runtools oauth list

# Disconnect
runtools oauth disconnect google

​

How Auto-Resolution Works

Tool needs credentials
    ↓
Check: per-request credentials passed?
    → YES: use them
    → NO: continue
    ↓
Check: stored credentials in DB?
    → YES: decrypt and use them
    → NO: continue
    ↓
Check: tool declares credentials.oauth.provider?
    → YES: call auth service GET /v1/oauth/token/:provider
           ↓
           Token expired?
              → YES: refresh via provider's token endpoint, update DB
              → NO: return current token
           ↓
           Map token via credentialMapping
           ↓
           Tool executes with fresh credentials
    → NO: run with empty credentials

​

Token Refresh

​

Background Daemon (Proactive)

1. Queries for connections with tokens expiring within 10 minutes
2. Decrypts refresh tokens
3. Calls each provider’s token refresh endpoint
4. Updates the DB with new access tokens and expiry times
5. Tracks failures to avoid retrying revoked tokens

​

On-Demand (Reactive)

1. The auth service refreshes the token immediately
2. Stores the new token
3. Returns the fresh token to the caller

​

BYOA (Bring Your Own App)

• The consent screen shows your app name instead of “RunTools”
• You control the scopes requested
• Your customers see your brand throughout the OAuth flow

​

Dashboard

​

API

# Register BYOA credentials
curl -X POST https://auth.runtools.ai/v1/oauth/byoa/google \
  -H "Authorization: Bearer rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-google-client-id.apps.googleusercontent.com",
    "client_secret": "your-google-client-secret",
    "scopes": ["https://www.googleapis.com/auth/gmail.modify"]
  }'

​

Declaring OAuth in Custom Tools

import { defineTool } from '@runtools/sdk';

export default defineTool({
  name: 'my-google-tool',
  description: 'Custom tool using Google OAuth',
  credentials: {
    required: ['accessToken'],
    schema: {
      accessToken: {
        type: 'string',
        description: 'Google OAuth2 access token',
      },
    },
    oauth: {
      provider: 'google',                                         // which provider to use
      scopes: ['https://www.googleapis.com/auth/drive.readonly'],  // required scopes
      credentialMapping: { accessToken: 'access_token' },          // map to token field
    },
  },
  actions: {
    list_files: {
      description: 'List Google Drive files',
      parameters: {
        type: 'object',
        properties: {
          query: { type: 'string', description: 'Search query' },
        },
        required: [],
      },
      execute: async (params, credentials) => {
        // credentials.accessToken is automatically a fresh Google token
        const res = await fetch('https://www.googleapis.com/drive/v3/files', {
          headers: { Authorization: `Bearer ${credentials.accessToken}` },
        });
        return await res.json();
      },
    },
  },
});

• { accessToken: 'access_token' } — maps credentials.accessToken to the OAuth access token
• { token: 'access_token' } — maps credentials.token to the OAuth access token

​

Security

​

API Reference