Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Connected Apps let users connect providers such as GitHub, Google, Slack, Microsoft, Discord, LinkedIn, and X. Tool Hub execution can then resolve provider credentials server-side without the caller passing raw OAuth tokens.
Raw OAuth token retrieval is not a public SDK method. Use connection management helpers and hosted tool execution instead of building your own token plumbing.

​
Connect With The CLI

runtools login
runtools oauth connect github
runtools oauth status
runtools oauth set-default github
runtools oauth disconnect github
Use custom scopes when needed: 
runtools oauth connect google \
  --scopes "https://www.googleapis.com/auth/gmail.modify"

​
Connect With The SDK

const { authUrl } = await rt.auth.connect('github', {
  scopes: ['repo', 'read:user'],
});

// Redirect the user to authUrl.

const connected = await rt.auth.isConnected('github');
const connections = await rt.auth.listConnections();

if (connections[0]) {
  await rt.auth.setDefault(connections[0].id);
}

​
How Tools Use Connections

When you run a Tool Hub action, RunTools resolves credentials in this order:
  1. Per-request credentials
  2. credentialOverrides that point at stored secrets
  3. Stored credentials for the installed tool
  4. Matching user or org secrets
  5. Connected OAuth account for the tool’s provider
const result = await rt.tools.execute('github', {
  action: 'list_repos',
  params: { owner: 'runtools-ai' },
});

​
BYOA Provider Configs

Bring-your-own-app configs let an organization use its own OAuth client for a provider. 
await rt.auth.setProviderConfig('github', {
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  scopes: 'repo,read:user',
});

const configs = await rt.auth.listProviderConfigs();
await rt.auth.deleteProviderConfig('github');
cURL
curl -X POST https://auth.runtools.ai/v1/oauth/configs \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "scopes": "repo,read:user"
  }'

​
Custom Tools

Custom tools declare OAuth needs in their credential spec. RunTools maps the connected provider token into the credential field before running the tool.
tools/my-google-tool.ts
import { defineTool } from '@runtools/sdk';

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

​
API Reference

MethodPathDescription
GET/v1/oauth/providersList providers
GET/v1/oauth/start/{provider}Start an OAuth connection flow
GET/v1/oauth/connectionsList connections
DELETE/v1/oauth/connections/{id}Disconnect by connection ID
POST/v1/oauth/connections/{id}/set-defaultMark a connection as default
GET/v1/oauth/status/{provider}Check provider connection status
GET/v1/oauth/configsList BYOA provider configs
POST/v1/oauth/configsCreate or update a BYOA provider config
DELETE/v1/oauth/configs/{provider}Delete a BYOA provider config