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 bind to it and use its actions.

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 -- it never touches application databases.
• 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.
• Provisions webhook listener URLs.
• Mounts OAuth endpoints (if defined).

Bind to an Application

Once deployed, connect the integration to any application:

1. Open an application in Studio.
2. Go to the Integrations tab.
3. Click Bind next to the integration.
4. Enter credentials (e.g. the Slack Bot Token) -- saved directly to the Secret Vault.

After binding:

• Applications can assign integration permissions to user roles.
• AI Agents receive the actions as callable tools automatically.

Credentials and OAuth

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.

Full Manifest Example

{
  "appId": "slack",
  "name": "Slack",
  "version": "1.0.0",
  "type": "integration",
  "configSchema": {
    "properties": {
      "botToken": {
        "type": "string",
        "platformSecret": "SLACK_BOT_TOKEN"
      },
      "webhookSecret": {
        "type": "string",
        "platformSecret": "SLACK_WEBHOOK_SECRET"
      }
    }
  },
  "actions": [
    { "id": "send_message",  "name": "Send Message",  "description": "Post a message to a channel" },
    { "id": "list_channels", "name": "List Channels",  "description": "List all public channels" },
    { "id": "add_reaction",  "name": "Add Reaction",   "description": "Add an emoji reaction to a message" }
  ],
  "webhooks": ["message", "reaction_added"],
  "userAuth": { "type": "redirect" },
  "instructions": "Use send_message to post to a channel by name or ID. list_channels returns public channels only.",
  "dataContract": []
}

Next Steps

• Build an Application -- the foundation every integration inherits.
• Secret Vault -- how credentials are stored and injected.
• For developers: REST API for integration catalog, binding, and configuration endpoints.