# How to Integrate Kaneo with Other Tools: A Complete Technical Guide

> Discover how to integrate Kaneo with Slack, GitHub, Discord and more using REST API, WebSockets, and React hooks. Streamline your workflow with this technical guide.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-02

---

**Kaneo integrates with external tools through a modular architecture that uses REST API endpoints, shared database schemas, WebSocket broadcasts, and reusable React hooks to connect services like Slack, GitHub, Gitea, Discord, and custom webhooks.**

Kaneo is designed as an extensible, open-source project management platform. This guide breaks down exactly how its integration system works under the hood, drawing directly from the [usekaneo/kaneo](https://github.com/usekaneo/kaneo) source code.

## Kaneo Integration Architecture Overview

All Kaneo integrations follow a consistent six-layer architecture. Understanding these layers shows how to integrate Kaneo with other tools using established patterns.

### 1. Backend API Endpoints

Each integration lives under a dedicated `/api/{integration}-integration` namespace. These routes are built with **Hono** and validated by **Valibot**.

In [`apps/api/src/slack-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/slack-integration/index.ts), the route definition looks like this:

```typescript
import { Hono } from 'hono';
import { createSlackIntegration, deleteSlackIntegration, getSlackIntegration } from './controllers';

export const slackIntegration = new Hono()
  .get('/', getSlackIntegration)
  .post('/', createSlackIntegration)
  .delete('/', deleteSlackIntegration);

```

This pattern repeats across GitHub (`/api/github-integration`), Gitea (`/api/gitea-integration`), Discord (`/api/discord-integration`), and webhook integrations.

### 2. Database Schema for Integrations

Integration data is stored in a shared `integration` table defined in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts). The schema includes:

- `type` — discriminator for the integration service (slack, github, gitea, etc.)
- `projectId` — association to the Kaneo project
- `config` — provider-specific JSON configuration
- OAuth tokens and refresh credentials

This unified approach lets Kaneo query all integrations for a project with a single database call.

### 3. Real-Time WebSocket Broadcasts

When integrations change, connected clients receive updates immediately. The broadcast system in [`apps/api/src/ws/broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/ws/broadcast-adapter.ts) supports both single-instance and multi-instance deployments:

```typescript
// apps/api/src/ws/broadcast-adapter.ts
export async function broadcastIntegrationChange(projectId: string, payload: any) {
  await broadcastAdapter.publish(`project:${projectId}:integration`, JSON.stringify(payload));
}

```

- **Development**: In-memory adapter
- **Production**: Redis-backed adapter for horizontal scaling

### 4. Frontend Fetchers and React Query Hooks

Each integration exposes typed fetcher functions and corresponding hooks. For example, Slack integration uses:

- **Fetcher**: [`apps/web/src/fetchers/slack-integration/create-slack-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/fetchers/slack-integration/create-slack-integration.ts)
- **Hook**: [`apps/web/src/hooks/mutations/slack-integration/use-slack-integration.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/hooks/mutations/slack-integration/use-slack-integration.ts)

These hooks automatically:
- Cache server state with React Query
- Invalidate related queries on mutation
- Surface errors via toast notifications

### 5. OAuth and Device Flow Authentication

For providers requiring OAuth (GitHub, Gitea, Discord) or device authorization, Kaneo uses a reusable [`auth-service.ts`](https://github.com/usekaneo/kaneo/blob/main/auth-service.ts) located at [`packages/mcp/src/auth/auth-service.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/auth/auth-service.ts). This service handles:

- Token exchange and storage
- Automatic token refresh
- Secure credential encryption

The device flow implementation at [`packages/mcp/src/auth/device-flow.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/auth/device-flow.ts) follows RFC 8628 for headless authentication scenarios.

### 6. RBAC Permission Enforcement

All integration routes enforce the same role-based access control as core Kaneo features. The middleware in [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts) validates that the requesting user has appropriate permissions (viewer, member, or admin) before allowing integration operations.

## Practical Integration Examples

### Connecting Slack to a Kaneo Project

Here's a complete React component that demonstrates how to integrate Kaneo with Slack using the provided hooks:

```tsx
import { useCreateSlackIntegration } from '@/hooks/mutations/slack-integration/use-slack-integration';
import { useGetSlackIntegration } from '@/hooks/queries/slack-integration/use-get-slack-integration';

function SlackConnect({ projectId }: { projectId: string }) {
  const { data: slack, isLoading } = useGetSlackIntegration(projectId);
  const createMutation = useCreateSlackIntegration(projectId);

  if (isLoading) return <p>Loading integration status...</p>;
  if (slack?.connected) return <p>✓ Slack is connected to this project.</p>;

  return (
    <button
      onClick={() => createMutation.mutate({ webhookUrl: 'https://hooks.slack.com/services/...' })}
      disabled={createMutation.isLoading}
    >
      {createMutation.isLoading ? 'Connecting...' : 'Connect Slack'}
    </button>
  );
}

```

The `useCreateSlackIntegration` hook handles POSTing to `/api/slack-integration` with proper error handling and cache invalidation.

### Implementing GitHub OAuth Server-Side

For GitHub integration, the OAuth callback controller in [`apps/api/src/github-integration/controllers/oauth-callback.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/github-integration/controllers/oauth-callback.ts) exchanges temporary codes for access tokens:

```typescript
import { Hono } from 'hono';
import { getGithubToken } from '@/mcp/auth/token-store';
import { upsertGithubIntegration } from '@/github-integration/service';

export const githubOAuthCallback = new Hono()
  .get('/', async (c) => {
    const code = c.req.query('code');
    const state = c.req.query('state'); // Contains projectId for association
    
    const token = await getGithubToken(code);
    await upsertGithubIntegration({ 
      userId: c.get('userId'), 
      projectId: state,
      token 
    });
    
    return c.redirect('/dashboard/settings/integrations');
  });

```

## Adding a Custom Integration to Kaneo

To integrate a new external tool with Kaneo, follow this implementation roadmap:

1. **Extend the database schema** — Add provider-specific fields to [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts)

2. **Create API routes** — Implement Hono routes in `apps/api/src/{service}-integration/index.ts` with Valibot validation

3. **Build controller logic** — Handle authentication, webhook verification, and business logic in `apps/api/src/{service}-integration/controllers/`

4. **Expose frontend fetchers** — Add typed HTTP wrappers in `apps/web/src/fetchers/{service}-integration/`

5. **Create React Query hooks** — Implement data fetching hooks in `apps/web/src/hooks/queries/{service}-integration/`

6. **Build UI components** — Add settings panels and connection buttons in `apps/web/src/components/integrations/`

7. **Update permissions** — Register any new required scopes in [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts)

8. **Write comprehensive tests** — Cover API endpoints in `tests/api/**` and full flows in `tests/api-integration/**`

## Key Source Files for Kaneo Integrations

| Component | Path | Purpose |
|-----------|------|---------|
| API route definitions | [`apps/api/src/slack-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/slack-integration/index.ts) | REST endpoint registration |
| Integration schema | [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) | Unified database structure |
| WebSocket broadcasting | [`apps/api/src/ws/broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/ws/broadcast-adapter.ts) | Real-time client updates |
| OAuth service | [`packages/mcp/src/auth/auth-service.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/auth/auth-service.ts) | Token management and refresh |
| Device flow | [`packages/mcp/src/auth/device-flow.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/auth/device-flow.ts) | RFC 8628 implementation |
| Frontend fetchers | `apps/web/src/fetchers/*-integration/*` | HTTP client abstractions |
| React Query hooks | `apps/web/src/hooks/queries/*-integration/` | Data synchronization |
| Integration UI | `apps/web/src/components/integrations/` | Settings and connection UI |
| Permission middleware | [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts) | RBAC enforcement |
| Test suites | `tests/api/**`, `tests/api-integration/**` | Verification coverage |

## Summary

- **Kaneo uses a standardized pattern** for all integrations: Hono API routes → controllers → database → WebSocket broadcast → React Query hooks
- **Existing integrations** (Slack, GitHub, Gitea, Discord, webhooks) demonstrate production-ready implementations you can reference
- **The `integration` table in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts)** serves as the central store for all connected services
- **Real-time synchronization** happens through [`apps/api/src/ws/broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/ws/broadcast-adapter.ts), supporting both single and multi-instance deployments
- **Adding new tools** requires consistent changes across eight layers: database, API, controllers, fetchers, hooks, UI, permissions, and tests

## Frequently Asked Questions

### What authentication methods does Kaneo support for integrations?

Kaneo supports three primary authentication patterns according to the source code: standard OAuth 2.0 for GitHub, Gitea, and Discord; OAuth Device Flow (RFC 8628) for headless or CLI scenarios via [`packages/mcp/src/auth/device-flow.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/auth/device-flow.ts); and simple webhook URL validation for services like Slack. The reusable [`auth-service.ts`](https://github.com/usekaneo/kaneo/blob/main/auth-service.ts) handles token storage, encryption, and automatic refresh across all OAuth providers.

### How does Kaneo keep integration data synchronized across clients?

Kaneo broadcasts integration changes through WebSocket messages using the adapter pattern in [`apps/api/src/ws/broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/ws/broadcast-adapter.ts). When any integration is created, updated, or deleted, the server publishes to a project-scoped channel (`project:${projectId}:integration`), and connected clients receive the payload instantly. The production configuration uses Redis as the broadcast backend to support multiple API instances.

### Can I integrate Kaneo with tools that aren't officially supported?

Yes. The modular architecture in [usekaneo/kaneo](https://github.com/usekaneo/kaneo) is designed for extension. You need to implement the eight-step pattern: database schema extension, Hono API routes, controller logic, frontend fetchers, React Query hooks, UI components, permission updates, and tests. Reference the existing `slack-integration` or `github-integration` directories as working templates.

### Where are integration credentials stored securely?

OAuth tokens and sensitive configuration are stored in the `integration` table's encrypted `config` column, defined in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts). The [`packages/mcp/src/auth/auth-service.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/auth/auth-service.ts) module handles encryption at rest and provides methods for secure token retrieval. Environment-specific encryption keys should be configured via the application's secure configuration system.