---
title: "Create Workspace Connector"
method: POST
path: "/api/v1/workspace-connectors"
tags: ["workspace-connectors"]
---

# Create Workspace Connector

`POST /api/v1/workspace-connectors`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/workspace-connectors`
- Auth: none declared

Provision a connector using the Resource Foundation.

Requires a plan with the ``connectors`` feature (XL, #1551); existing
connectors on lower plans keep working. The ``max_connectors`` seat cap
applies second, inside ``ConnectorProvisioningService``.

## Headers

- `authorization` string, nullable

## Request body

- WorkspaceConnectorCreateRequest: Request body for provisioning an ai-worker connector.
  - `connector_type` 'slack' | 'discord' | 'teams', required: Connector backend to provision
  - `resource_id` string, required: Workspace-scoped resource slug for ingested chat events
  - `display_name` string, nullable
  - `oauth_tokens` object, nullable: OAuth token bundle; stored Fernet-encrypted
  - `pii_guardrail_config` object, nullable: PII guardrail config for ai-worker pre-compile
  - `litellm_virtual_key_id` string, nullable
  - `virtual_key_valid_until` string, date-time, nullable
  - `quota_events_per_hour` integer
  - `context_id` string, uuid, nullable: Existing write-target context
  - `auto_create_context_name` string, nullable: Create a fresh private context with this name
  - `llm_config` object, nullable: BYO LLM bundle; Fernet-encrypted
  - `channel_ids` unknown[], nullable: Ingest channel selection
    - unknown
  - `locale` string, nullable: Worker pre-compile locale. Must map to the worker Locale contract ('en' | 'ja'); common BCP-47 forms are normalized (ja-JP → ja). See models.worker_runtime.WORKER_LOCALES (#1377).
  - `external_team_id` string, nullable: Platform team id (worker dispatch key)
  - `app_key` string: Stable platform app identity selector
  - `slack_install_handle` string, nullable: One-time handle from the Slack OAuth callback; resolved server-side to oauth_tokens + external_team_id (bot token never sent by client)
  - `runtime` WorkerRuntimeConfig: Complete non-secret, installation-scoped worker runtime contract.
    - `buffer` WorkerRuntimeBufferConfig: Tenant-owned buffer limits; connection coordinates are intentionally absent.
      - `ttl_seconds` integer
      - `max_len` integer
    - `flush` WorkerRuntimeFlushConfig: Per-connector topic flush thresholds.
      - `silence_seconds` integer
      - `volume_tokens` integer
      - `max_tracked_topics` integer
    - `supervisor` WorkerRuntimeSupervisorConfig: Per-connector supervisor cadence and shutdown budget.
      - `tick_seconds` number
      - `shutdown_flush_timeout_seconds` number
    - `lifecycle` WorkerRuntimeLifecycleConfig: Connector lifecycle propagation behavior.
      - `deletion_mode` 'forget' | 'redact'
      - `redacted_summary` string
      - `dormant_summary` string
      - `edited_summary` string
    - `continuity` WorkerRuntimeContinuityConfig: Per-connector topic-continuity thresholds.
      - `time_window_minutes` integer
      - `semantic_threshold` number
      - `semantic_check_enabled` boolean
    - `vision_enabled` boolean
    - `team_scope_filter_enabled` boolean
    - `channel_allowlist_enabled` boolean
    - `mention_answer_enabled` boolean
    - `answer_relevance_threshold` number
    - `answer_timeout_sec` number
    - `memory_link_template` string, nullable
    - `entity_extraction_enabled` boolean
    - `entity_max` integer

## Response `201`

Successful Response

- WorkspaceConnectorCreateResponse: Connector setup response. The token + KMC key are shown exactly once.
  - `connector_id` string, uuid, required
  - `connector_type` string, required
  - `app_key` string, required
  - `resource_id` string, required
  - `context_id` string, uuid, nullable
  - `token_id` string, required: Public id of the connector's resource token (`rtok_` + 22 base62 characters)
  - `token` string, required: Plaintext resource token; save immediately
  - `kmc_api_key` string, nullable: Plaintext KMC write key; shown once (registration flow only)
  - `quota_events_per_hour` integer, required
  - `idempotency_key_prefix` string, required

## Other responses

- `409`: `RES-002`. For a platform team that is already connected, `details.reason` says where (#1753): `connector_team_connected_here` (this workspace; `details.connector_id` and `details.display_name` name the existing connector — edit it instead; `details.token_refreshed: true` is added when the request carried a Slack install handle and that install's bot token was stored on the existing connector, #1880) or `connector_team_connected_elsewhere` (another workspace; no other details). A `resource_id` clash is a 409 without `reason`.
- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)