Build an Integration

An Integration bridges RootCX to an external API -- Slack, Stripe, Twilio, or any service. It exposes actions that your applications and AI agents can call, and webhooks that listen for incoming events. Credentials are stored in the encrypted Secret Vault and injected at runtime.

Integrations inherit RBAC and Audit Logs. Once deployed, any application or AI agent in your ecosystem can use its actions — no binding step required.

Create an Integration with Forge

Open the AI Forge in Studio. Describe the external service, its actions, and credentials.

Example prompt:

"Create a Slack integration. It needs an action 'Send Message' that takes a channel and text. It requires a Bot Token credential. Add a webhook to listen for incoming channel messages."

The Forge scaffolds the manifest, config schema, and backend handlers.

What Gets Generated

Manifest

The manifest declares the integration type, its credentials, actions, and webhooks:

{
  "appId": "slack",
  "name": "Slack",
  "version": "1.0.0",
  "type": "integration",
  "configSchema": {
    "properties": {
      "botToken": {
        "type": "string",
        "platformSecret": "SLACK_BOT_TOKEN"
      }
    }
  },
  "actions": [
    {
      "id": "send_message",
      "name": "Send Message",
      "description": "Post a message to a Slack channel",
      "inputSchema": {
        "type": "object",
        "properties": {
          "channel": { "type": "string" },
          "text": { "type": "string" }
        },
        "required": ["channel", "text"]
      }
    }
  ],
  "webhooks": ["message"]
}

Key concepts:

• type: "integration" marks this app as an integration.
• configSchema defines the credentials the integration needs. The platformSecret mapping stores the value in the encrypted vault.
• actions are operations other apps and agents can call.
• webhooks are events the integration listens for from the external service.
• instructions is a free-form string surfaced to AI agents via the list_integrations tool. Use it to explain usage patterns, parameter conventions, or quirks of the external API.

Backend

The Forge also generates backend/index.ts with handlers for actions and webhooks. You can review and edit it in the Studio editor.

Deploy

Hit Run (F5). The platform:

• Registers the integration in the catalog.
• Creates RBAC permissions for each action (e.g. integration:slack:send_message).
• Provisions webhook listener URLs.
• Mounts OAuth endpoints (if defined).

Using an Integration

Once deployed, any application or AI agent can use the integration's actions. No explicit binding step is required — access is governed by RBAC permissions.

Configure Credentials

1. Go to Integrations in Studio.
2. Find the integration and click Configure.
3. Enter credentials (e.g. the Slack Bot Token) — saved directly to the Secret Vault.

Credential Models

Integrations support two credential models:

• Platform secrets -- a single set of credentials shared across the platform (e.g. a bot token). Configured via the platformSecret mapping in the manifest.
• Per-user OAuth -- each user authenticates individually with the external service. The platform handles the OAuth flow and encrypts credentials per user.

Credential Delegation for AI Agents

When an AI agent calls an integration action, it can delegate credentials from the invoking user. This allows the agent to act on behalf of the user with their OAuth tokens, without storing separate credentials for the agent.

From the SDK

import { useIntegration } from "@rootcx/sdk";

const { connected, connect, call } = useIntegration("slack");

// Connect (OAuth or credentials)
await connect();

// Call an action
await call("send_message", { channel: "#general", text: "Hello!" });

From the API

POST /api/v1/integrations/slack/actions/send_message
{ "channel": "#general", "text": "Hello!" }

API Endpoints

Next Steps

• Build an Application -- the foundation every integration inherits.
• Secret Vault -- how credentials are stored and injected.
• REST API -- full endpoint reference.