Unclassified

How to Build on IntegrateWise Platform

Guide for external frontend apps consuming the platform.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Your Frontend App                        │
├─────────────────────────────────────────────────────────────┤
│  React / Next.js / Vue / Svelte / React Native / Flutter   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              IntegrateWise Gateway                          │
│         INTEGRATEWISE_GATEWAY_URL                            │
├─────────────────────────────────────────────────────────────┤
│  Auth (JWT) → Tenant Resolution → Rate Limiting → Routing  │
└─────────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
      ┌──────────┐   ┌──────────┐   ┌──────────┐
      │Connector │   │  Spine   │   │Capability│
      │  APIs    │   │  Data    │   │  Engine  │
      └──────────┘   └──────────┘   └──────────┘
            │               │               │
            ▼               ▼               ▼
      Salesforce      Accounts        Execute
      HubSpot         Contacts        Actions
      Slack           Deals           Govern
      GitHub          Tasks           Approve

Quick Start (5 minutes)

Set INTEGRATEWISE_GATEWAY_URL to the Gateway origin for the intended
environment. Use the Gateway only; platform workers and services are not direct
client endpoints.

0. Discover Packages, Services, and Endpoints

No credentials are needed to discover the read-only public contract:

curl "$INTEGRATEWISE_GATEWAY_URL/api/v1/platform"
curl "$INTEGRATEWISE_GATEWAY_URL/api/v1/platform/packages"
curl "$INTEGRATEWISE_GATEWAY_URL/api/v1/platform/services"
curl "$INTEGRATEWISE_GATEWAY_URL/api/v1/platform/openapi.json"

The response describes only Gateway-facing contracts. It does not publish
service bindings, direct worker URLs, provider credentials, or tenant data.

1. Get Credentials

# Sign in via Clerk
open "https://accounts.integratewise.ai/sign-in"

# After login, you get:
export INTEGRATEWISE_API_TOKEN="eyJhbGci..."
export INTEGRATEWISE_TENANT_ID="tenant_abc123"

2. Verify Gateway Reachability

curl "$INTEGRATEWISE_GATEWAY_URL/health"

# → {"status":"ok","service":"gateway","ts":...}

3. Fetch Data

# Get your workspace data
curl -H "Authorization: Bearer $INTEGRATEWISE_API_TOKEN" \
     -H "x-tenant-id: $INTEGRATEWISE_TENANT_ID" \
     "$INTEGRATEWISE_GATEWAY_URL/api/v1/workspace/projection/SALES"

# → Full workbench with accounts, contacts, deals, tasks

Use Cases

1. CRM Dashboard

Build a sales dashboard showing accounts, deals, and pipeline.

// Fetch sales workbench
const workbench = await fetch(
  "https://gateway.dev.integratewise.ai/api/v1/workspace/projection/SALES",
  {
    headers: {
      "Authorization": `Bearer ${token}`,
      "x-tenant-id": tenantId,
    },
  }
).then(r => r.json());

// Render
const accounts = workbench.entities.account || [];
const deals = workbench.entities.deal || [];
const tasks = workbench.entities.task || [];

return (
  <Dashboard>
    <Metrics accounts={accounts.length} deals={deals.length} />
    <AccountList accounts={accounts} />
    <DealPipeline deals={deals} />
    <TaskList tasks={tasks} />
  </Dashboard>
);

2. Integration Marketplace

Let users connect data sources (Salesforce, HubSpot, etc.).

Connectors are tenant-level assets. Once connected, all apps share the same connection.

                    Tenant

                       │

               Connector Registry

                       │

      Salesforce (Connected)
      Slack (Connected)
      Gmail (Connected)
      GitHub (Connected)

           │           │          │

     Customer Zero   Marketplace   Admin
           │           │          │
           └───────────┼──────────┘
                       │
                 Same Connections

// Get available connectors
const catalog = await fetch(
  "https://gateway.dev.integratewise.ai/api/v1/workspace/connectors/catalog",
  {
    headers: {
      "Authorization": `Bearer ${token}`,
      "x-tenant-id": tenantId,
    },
  }
).then(r => r.json());

// Render marketplace
return (
  <Marketplace>
    {catalog.connectors.map(connector => (
      <ConnectorCard
        key={connector.id}
        name={connector.name}
        category={connector.category}
        status={connector.status}
        onConnect={() => connectConnector(connector.id)}
      />
    ))}
  </Marketplace>
);

// Connect a connector (OAuth flow)
async function connectConnector(connectorId: string) {
  // 1. Start OAuth flow
  const { auth_url } = await fetch(
    `https://gateway.dev.integratewise.ai/api/v1/integrations/${connectorId}/authorize`,
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${token}`,
        "x-tenant-id": tenantId,
      },
    }
  ).then(r => r.json());

  // 2. Redirect user
  window.location.href = auth_url;
}

What's shared at tenant level:

  • OAuth tokens
  • Refresh tokens
  • Webhooks
  • Sync cursors
  • Provider schemas
  • Field mappings
  • Connector configuration

What's frontend-specific:

  • UI preferences (layout, recent views, local state)

3. AI Assistant

Build an AI assistant that can query workspace data.

// Ask AI to analyze data
const response = await fetch("https://gateway.dev.integratewise.ai/api/v1/brainstorm", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "x-tenant-id": tenantId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "What are the top 5 deals this quarter?",
    context: { department: "SALES" },
  }),
}).then((r) => r.json());

// response.insights = [
//   { title: "Top Deal", value: "Acme Corp - $120K", confidence: 0.95 },
//   ...
// ]

4. Automated Workflows

Execute capabilities programmatically.

// Read data from Salesforce
const accounts = await fetch("https://gateway.dev.integratewise.ai/api/v1/capabilities/resolve", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "x-tenant-id": tenantId,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    capability: "salesforce:read-accounts",
    params: { limit: 100, filter: { industry: "Technology" } },
  }),
}).then((r) => r.json());

// Process and write back
for (const account of accounts.result.accounts) {
  await fetch("https://gateway.dev.integratewise.ai/api/v1/capabilities/resolve", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "x-tenant-id": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      capability: "salesforce:update-account",
      params: {
        id: account.id,
        fields: { last_reviewed: new Date().toISOString() },
      },
    }),
  });
}

5. Mobile App

React Native integration.


const platform = createPlatformClient({
  baseUrl: "https://gateway.integratewise.ai",
  getAccessToken: () => AsyncStorage.getItem("token"),
});

const manifest = await platform.capability.resolve();

// Render
return (
  <View>
    <Text>Available actions: {manifest.capabilities.length}</Text>
    <FlatList
      data={manifest.capabilities}
      keyExtractor={item => item.id}
      renderItem={({ item }) => (
        <CapabilityCard capability={item} />
      )}
    />
  </View>
);

React Hooks

useWorkbench

function useWorkbench(token: string, tenantId: string, department: string) {
  const [workbench, setWorkbench] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    setLoading(true);
    fetch(
      `https://gateway.dev.integratewise.ai/api/v1/workspace/projection/${department}`,
      {
        headers: {
          "Authorization": `Bearer ${token}`,
          "x-tenant-id": tenantId,
        },
      }
    )
      .then(r => r.json())
      .then(setWorkbench)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [token, tenantId, department]);

  return { workbench, loading, error };
}

// Usage
function Dashboard() {
  const { workbench, loading } = useWorkbench(token, tenantId, "SALES");

  if (loading) return <Spinner />;

  return (
    <div>
      <h1>Sales Dashboard</h1>
      <p>Accounts: {workbench.entities.account.length}</p>
      <p>Deals: {workbench.entities.deal.length}</p>
    </div>
  );
}

useConnectors

function useConnectors(token: string, tenantId: string) {
  const [connectors, setConnectors] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch("https://gateway.dev.integratewise.ai/api/v1/workspace/connectors/catalog", {
      headers: {
        Authorization: `Bearer ${token}`,
        "x-tenant-id": tenantId,
      },
    })
      .then((r) => r.json())
      .then((data) => setConnectors(data.connectors))
      .finally(() => setLoading(false));
  }, [token, tenantId]);

  const connect = async (connectorId: string) => {
    const { auth_url } = await fetch(
      `https://gateway.dev.integratewise.ai/api/v1/integrations/${connectorId}/authorize`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${token}`,
          "x-tenant-id": tenantId,
        },
      }
    ).then((r) => r.json());
    window.location.href = auth_url;
  };

  return { connectors, loading, connect };
}

useCapabilities

function useCapabilities(getAccessToken: () => Promise<string | null>) {
  const [capabilities, setCapabilities] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    createPlatformClient({
      baseUrl: "https://gateway.integratewise.ai",
      getAccessToken,
    })
      .capability.resolve()
      .then((data) => setCapabilities(data.capabilities))
      .finally(() => setLoading(false));
  }, [getAccessToken]);

  const prepare = async (capabilityId: string, input: Record<string, unknown>) => {
    const client = createPlatformClient({
      baseUrl: "https://gateway.integratewise.ai",
      getAccessToken,
    });
    return client.capability.prepare(capabilityId, input);
  };

  return { capabilities, loading, prepare };
}

Complete Example


function IntegrateWiseApp({ token, tenantId }) {
  const { workbench } = useWorkbench(token, tenantId, "SALES");
  const { connectors, connect } = useConnectors(token, tenantId);
  const { capabilities, execute } = useCapabilities(token, tenantId);

  return (
    <div className="app">
      
      <header>
        <h1>IntegrateWise</h1>
        <p>Tenant: {tenantId}</p>
      </header>

      
      <section>
        <h2>Connected Integrations</h2>
        {connectors
          .filter(c => c.status === "connected")
          .map(connector => (
            <div key={connector.id}>
              <span>{connector.name}</span>
              <span>{connector.status}</span>
            </div>
          ))}
        <button onClick={() => connect("salesforce")}>
          + Connect Salesforce
        </button>
      </section>

      
      <section>
        <h2>Workspace Data</h2>
        <div className="metrics">
          <div>Accounts: {workbench?.entities?.account?.length || 0}</div>
          <div>Deals: {workbench?.entities?.deal?.length || 0}</div>
          <div>People: {workbench?.entities?.person?.length || 0}</div>
        </div>

        <h3>Recent Deals</h3>
        {workbench?.entities?.deal?.slice(0, 5).map(deal => (
          <div key={deal.id}>
            <span>{deal.name}</span>
            <span>{deal.metadata.amount}</span>
          </div>
        ))}
      </section>

      
      <section>
        <h2>Available Actions</h2>
        {capabilities.map(cap => (
          <button
            key={cap.id}
            onClick={() => execute(cap.id, { limit: 10 })}
          >
            {cap.name}
          </button>
        ))}
      </section>
    </div>
  );
}

Environment Variables

# Required
INTEGRATEWISE_API_TOKEN=eyJhbG...      # JWT from OAuth
INTEGRATEWISE_TENANT_ID=tenant_abc123   # Your workspace tenant ID

# Optional
INTEGRATEWISE_BASE_URL=https://gateway.dev.integratewise.ai
INTEGRATEWISE_USER_ID=user-123
INTEGRATEWISE_ORG_ID=org-789

Error Handling


async function safeFetch<T>(fn: () => Promise<T>): Promise<T | null> {
  try {
    return await fn();
  } catch (error) {
    if (error instanceof ApiError) {
      switch (error.status) {
        case 401:
          // Token expired — refresh or redirect to login
          redirectToLogin();
          break;
        case 403:
          // No permission — show error
          showError("You don't have permission to access this resource");
          break;
        case 429:
          // Rate limited — retry after delay
          const retryAfter = error.details?.retryAfter || 60;
          await new Promise((r) => setTimeout(r, retryAfter * 1000));
          return safeFetch(fn);
        default:
          console.error(error);
      }
    }
    return null;
  }
}

Resources