Hosted Connect

Hosted Connect lets a product built on Runtools ask its own users to connect their own third-party accounts. End users do not create Runtools accounts. Your product keeps its own auth system, passes a stable externalUserId, and Runtools stores credentials scoped to:

builder org + appId + externalUserId + tool

Use this when you build an agent product like Atlas and each customer needs to connect their own Stripe, Gmail, Sheets, Slack, or API-key-backed tools.

Create connect sessions from your server. Keep your Runtools API key server-side and only send the returned connectUrl to the browser.

Hosted Connect vs. Connected Apps

Surface	Owner	Used for
Connected Apps	Your Runtools user or organization	Internal dashboard tools and agents that use your own connected accounts
Hosted Connect	Your product’s end users	Customer-owned accounts for products you build on Runtools

Connections are app-scoped by default. A Gmail connection for atlas does not automatically become a Gmail connection for iris or any other product.

Create a product app

Configure one app per product. The appId is your stable product identifier, such as atlas.

import { RunTools } from '@runtools-ai/sdk';

const rt = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY,
});

await rt.connect.upsertApp({
  appId: 'atlas',
  slug: 'atlas',
  name: 'Atlas',
  allowedRedirectUrls: [
    'https://atlas.example.com/settings/integrations',
  ],
  allowedToolSlugs: [
    'stripe',
    'quickbooks',
    'xero',
    'google-sheets',
    'gmail',
    'slack',
    'hubspot',
  ],
  oauthAppPolicy: 'auto',
});

oauthAppPolicy controls which OAuth client is used:

Policy	Behavior
`auto`	Use an app-specific custom OAuth app, then an org default, then Runtools-managed OAuth when available
`custom_required`	Require the builder to configure a custom OAuth app for this product
`runtools_managed_only`	Always use the Runtools-managed OAuth app when available

Create a connect session

When a signed-in product user clicks “Connect integrations”, create a short-lived hosted connect session from your server.

const session = await rt.connect.createSession({
  appId: 'atlas',
  externalUserId: currentUser.id,
  email: currentUser.email,
  name: currentUser.name,
  integrations: ['stripe', 'google-sheets', 'gmail'],
  returnUrl: 'https://atlas.example.com/settings/integrations',
  successUrl: 'https://atlas.example.com/settings/integrations?connected=1',
});

return Response.json({
  connectUrl: session.connectUrl,
});

Open session.connectUrl in the browser. The hosted page shows the requested integrations, starts OAuth where needed, and collects API-key-style credentials for tools that use secrets instead of OAuth.

window.location.href = connectUrl;

Run an agent with that user’s connections

When your product runs an agent, pass the same app and user scope.

const run = await rt.agent.run(
  'atlas-agent',
  'Summarize revenue, cash, runway, and finance risks for this month.',
  {
    endUser: {
      appId: 'atlas',
      externalUserId: currentUser.id,
    },
  },
);

Tool execution resolves credentials only from that end user’s app-scoped connections. If the required connection is missing, the run returns connect_required instead of falling back to builder or org credentials. Agent-runtime tool calls are capability-scoped internally. The model, sandbox, and managed runtime can request a tool action, but they cannot choose credentialScope, endUser, raw credentials, or org secret overrides. Runtools derives that authority from the agent run and Hosted Connect app/user scope.

Use Hosted Connect from channels

For Telegram, WhatsApp, Slack, Discord, iMessage, or SMS products, the developer connects the channel once and end users only chat with it. The channel credential is the transport, not the customer data identity. Bind the channel to your product app, then link each provider sender id to the same appId + externalUserId you use for Hosted Connect:

await rt.channels.bindProductChannel('atlas', {
  agentChannelId: channel.id,
  identityPolicy: 'link_required',
  groupPolicy: 'sender_scoped',
});

await rt.channels.linkProductChannelUser({
  appId: 'atlas',
  agentChannelId: channel.id,
  externalUserId: telegramUserId,
  productExternalUserId: currentUser.id,
});

When the linked sender messages the channel, Runtools starts the agent with:

{
  endUser: {
    appId: 'atlas',
    externalUserId: currentUser.id,
  }
}

Missing product-user connections still return connect_required. The channel worker does not fall back to builder Connected Apps, org defaults, or another product user’s credentials.

Run tools directly

You can also execute Tool Hub actions with end-user scope.

const result = await rt.tools.execute('stripe', {
  action: 'list_customers',
  params: { limit: 10 },
  credentialScope: 'end_user',
  endUser: {
    appId: 'atlas',
    externalUserId: currentUser.id,
  },
});

When endUser is present, RunTools enforces credentialScope: 'end_user' even if you omit it. Passing it explicitly makes your intent clear. If the user connected multiple accounts for the same tool, pass a connection selector.

const { connections } = await rt.connect.listConnections({
  appId: 'atlas',
  externalUserId: currentUser.id,
});

await rt.tools.execute('gmail', {
  action: 'list_emails',
  params: { query: 'is:unread' },
  credentialScope: 'end_user',
  endUser: {
    appId: 'atlas',
    externalUserId: currentUser.id,
    connectionIds: connections
      .filter((connection) => connection.toolSlug === 'gmail')
      .map((connection) => connection.id),
  },
});

List connections

Show connection status in your product’s settings page.

const { connections } = await rt.connect.listConnections({
  appId: 'atlas',
  externalUserId: currentUser.id,
});

Each connection includes the tool slug, provider, account label, status, default flag, and timestamps. Raw tokens and secret values are never returned.

API-key-backed tools

Some tools use API keys or secrets instead of OAuth. The hosted connect page can collect those values and store them through the tools service. If you build your own connect UI, post the values through the connect session instead of storing them in your product database.

await rt.connect.storeSecretCredentials(session.id, {
  toolSlug: 'posthog',
  accountLabel: 'Production Project',
  credentials: {
    POSTHOG_API_KEY: userSubmittedKey,
  },
});

The credential is write-only to the product and encrypted by Runtools.

Usage and audit

Usage is attributed by app and end user so builders can report, rebill, and debug without exposing credentials.

const usage = await rt.connect.getAppUsage('atlas', { days: 30 });

const audit = await rt.connect.listAuditEvents({
  appId: 'atlas',
  externalUserId: currentUser.id,
  limit: 50,
});

Audit events include connection IDs, provider/tool labels, app IDs, external user IDs, event types, and timestamps. They never include raw credential values.

Custom OAuth apps

By default, Hosted Connect can use Runtools-managed OAuth. If you want the provider consent screen to show your own app name, configure a custom OAuth app.

await rt.auth.setProviderConfig('google', {
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  scopes: 'openid,email,https://www.googleapis.com/auth/gmail.readonly',
  appId: 'atlas',
});

You can configure a provider once for the organization, or override it for a single app by passing appId. Hosted Connect resolves app-specific config first, then org-level config, then Runtools-managed OAuth when the app policy allows it.

REST endpoints

The SDK uses the Auth and Tools service URLs internally. If you call REST directly, use these endpoints from your server:

Method	URL	Description
`POST`	`https://auth.runtools.ai/v1/connect/apps`	Create or update a product app
`POST`	`https://auth.runtools.ai/v1/connect/sessions`	Create a hosted connect session
`GET`	`https://auth.runtools.ai/v1/connect/sessions/{sessionId}`	Read public connect session metadata
`GET`	`https://auth.runtools.ai/v1/connect/connections?appId=atlas&externalUserId=user_123`	List one end user’s product-scoped connections
`GET`	`https://auth.runtools.ai/v1/connect/apps/{appId}/usage`	Read app-scoped usage
`GET`	`https://auth.runtools.ai/v1/connect/audit-events`	Export connection audit events
`POST`	`https://tools.runtools.ai/v1/connect/sessions/{sessionId}/secrets`	Store API-key-style credentials through a connect session

Authenticated Auth service calls accept the same Runtools API key as a bearer token:

curl -X POST https://auth.runtools.ai/v1/connect/sessions \
  -H "Authorization: Bearer $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "atlas",
    "externalUserId": "user_123",
    "integrations": ["stripe", "gmail"],
    "returnUrl": "https://atlas.example.com/settings/integrations"
  }'

Production checklist

Use a stable externalUserId from your product, not an email address that can change.
Create sessions server-side only.
Keep allowedRedirectUrls strict.
Keep allowedToolSlugs limited to tools your product actually needs.
Never use builder credentials for customer-data tool calls.
Treat missing end-user credentials as a connect-required state in your product UI.
Show connection status and reconnect actions inside your product settings.

Getting Started

Platform

Core Features

Advanced

Hosted Connect vs. Connected Apps

Create a product app

Create a connect session

Run an agent with that user’s connections

Use Hosted Connect from channels

Run tools directly

List connections

API-key-backed tools

Usage and audit

Custom OAuth apps

REST endpoints

Production checklist

​Hosted Connect vs. Connected Apps

​Create a product app

​Create a connect session

​Run an agent with that user’s connections

​Use Hosted Connect from channels

​Run tools directly

​List connections

​API-key-backed tools

​Usage and audit

​Custom OAuth apps

​REST endpoints

​Production checklist

Hosted Connect vs. Connected Apps

Create a product app

Create a connect session

Run an agent with that user’s connections

Use Hosted Connect from channels

Run tools directly

List connections

API-key-backed tools

Usage and audit

Custom OAuth apps

REST endpoints

Production checklist