OAuth & Connected Apps

Connected Apps let a user link a third-party account once — GitHub, Google, Slack, Microsoft, and the rest of the org’s enabled providers — and then every tool that needs that provider just works. Runtools mints and refreshes the token server-side at call time; the access token never passes through your code or an agent’s prompt. If you are building a product on Runtools and your product’s users need to connect their own accounts, use Hosted Connect instead. Connected Apps are for the authenticated Runtools user or org; Hosted Connect is for app-scoped customer connections such as atlas + customer_123 + gmail. The provider catalog comes from GET /v1/oauth/providers. Most providers use a browser redirect flow. openai-codex uses a device-code flow when it is enabled.

Raw OAuth token retrieval is internal-only service plumbing. Use connection management helpers and hosted tool execution instead of building your own token exchange or token storage.

Connect With The CLI

runtools login
runtools oauth connect github
runtools oauth status
runtools oauth set-default <connection-id>
runtools oauth disconnect <connection-id>

The CLI supports browser redirect providers such as github, google, slack, discord, microsoft, linkedin, and x. 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);   // pick the default account
  await rt.auth.disconnect(connections[0].id);   // or remove a connection
}

How Tools Use Connections

When you run a Tool Hub action, RunTools resolves credentials in this order and only fills missing required credential fields:

Per-request credentials
credentialOverrides that point at stored secrets
Stored credentials for the installed tool
Matching user or org secrets
Connected OAuth account for the tool’s provider

Secret fallbacks use normalized names. For example, a required field named apiKey maps to the secret name APIKEY; use credentialOverrides when you want a different secret name.

const result = await rt.tools.execute('github', {
  action: 'list_repos',
  params: { owner: 'runtools-ai' },
});

If multiple accounts are connected for the same provider, execution uses the user’s default connection unless you pass an account selector. The selector can be a human-readable email, username, display name, provider account ID, or exact connection ID from Connected Apps:

await rt.tools.execute('gmail', {
  action: 'list_emails',
  params: { query: 'is:unread' },
  oauth: {
    account: 'artkara2002@gmail.com',
  },
});

Agents receive optional connected_account and connected_connection_id inputs on OAuth-backed tools. Prefer connected_account so the model can use labels users naturally mention, such as an email address or GitHub username.

BYOA Provider Configs

Bring-your-own-app configs let an organization use its own OAuth client for a provider. Creating, listing, updating, or deleting provider configs requires credential-admin access.

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');

When a BYOA config is enabled, OAuth start uses the organization’s client ID, client secret, and custom scopes. If it is absent or disabled, RunTools falls back to the platform provider configuration when that provider is registered.

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-ai/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();
      },
    },
  },
});

If a tool has an OAuth credential spec and no matching connection exists, hosted execution reports the missing credential through the normal tool execution error path. The caller never receives the provider access token directly.

API Reference

Method	Path	Description
`GET`	`/v1/oauth/providers`	List providers
`GET`	`/v1/oauth/start/{provider}`	Start an OAuth connection flow
`POST`	`/v1/oauth/device/start/{provider}`	Start a device-code OAuth flow for providers that use one
`POST`	`/v1/oauth/device/status/{provider}`	Poll a device-code OAuth attempt
`GET`	`/v1/oauth/connections`	List connections
`GET`	`/v1/oauth/connections/{id}`	Get connection metadata
`DELETE`	`/v1/oauth/connections/{id}`	Disconnect by connection ID
`POST`	`/v1/oauth/connections/{id}/set-default`	Mark a connection as default
`GET`	`/v1/oauth/status/{provider}`	Check provider connection status
`GET`	`/v1/oauth/configs`	List BYOA provider configs
`POST`	`/v1/oauth/configs`	Create or update a BYOA provider config
`PATCH`	`/v1/oauth/configs/{provider}`	Enable or disable a BYOA provider config
`DELETE`	`/v1/oauth/configs/{provider}`	Delete a BYOA provider config

Internal services also call /v1/oauth/token/{provider} and /v1/oauth/export/{provider} with internal scopes. Those endpoints are not public customer APIs.

Getting Started

Platform

Core Features

Advanced

OAuth & Connected Apps

Connect With The CLI

Connect With The SDK

How Tools Use Connections

BYOA Provider Configs

Custom Tools

API Reference

​Connect With The CLI

​Connect With The SDK

​How Tools Use Connections

​BYOA Provider Configs

​Custom Tools

​API Reference

Connect With The CLI

Connect With The SDK

How Tools Use Connections

BYOA Provider Configs

Custom Tools

API Reference