> ## Documentation Index
> Fetch the complete documentation index at: https://doc.codika.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Integrations

> Configure, list, and delete integrations (API keys, credentials) for organizations and process instances via the CLI

## When to use

* After deploying a use case that requires integrations (OpenAI, Supabase, etc.)
* When setting up a new organization with required API keys
* When rotating or updating integration credentials
* When checking which integrations are connected

## Prerequisites

* API key with `integrations:manage` scope
* For process instance integrations: `project.json` with `devProcessInstanceId`

## Subcommands

| Command  | Description                                       |
| -------- | ------------------------------------------------- |
| `set`    | Create or update an integration                   |
| `list`   | List integrations and their status                |
| `delete` | Delete an integration                             |
| `schema` | Fetch n8n credential schema for a credential type |

***

## `codika integration set`

Creates an integration by encrypting secrets client-side and sending them to the platform.

```bash theme={null}
codika integration set <integrationId> [options]
```

### Arguments

| Argument        | Description                                                  |
| --------------- | ------------------------------------------------------------ |
| `integrationId` | Integration ID (e.g., `openai`, `supabase`, `cstm_acme_crm`) |

### Options

| Option                        | Description                                     | Default             |
| ----------------------------- | ----------------------------------------------- | ------------------- |
| `--secret <KEY=VALUE>`        | Secret field (repeatable)                       | —                   |
| `--secrets <json>`            | JSON string with all secrets                    | —                   |
| `--secrets-file <path>`       | Path to JSON file with secrets                  | —                   |
| `--metadata <KEY=VALUE>`      | Metadata field (repeatable)                     | —                   |
| `--context-type <type>`       | `organization`, `member`, or `process_instance` | Auto-detected       |
| `--process-instance-id <id>`  | Process instance ID                             | From `project.json` |
| `--path <path>`               | Path to use case folder                         | Current directory   |
| `--project-file <path>`       | Custom project file                             | `project.json`      |
| `--environment <env>`         | `dev` or `prod`                                 | `dev`               |
| `--custom-schema-file <path>` | Custom integration schema JSON                  | —                   |
| `--force`                     | Delete existing and recreate                    | `false`             |
| `--profile <name>`            | CLI profile to use                              | Active profile      |
| `--api-key <key>`             | Override API key                                | —                   |
| `--json`                      | Output as JSON                                  | `false`             |

### Secret input priority

Secrets are merged with this priority (highest wins):

1. `--secret KEY=VALUE` flags
2. `--secrets '{"KEY":"VALUE"}'` JSON string
3. `--secrets-file path.json` file

### Examples

```bash theme={null}
# Simple API key
codika integration set openai --secret OPENAI_API_KEY=sk-proj-xxx

# Multi-field credentials
codika integration set supabase \
  --secret SUPABASE_HOST=https://abc.supabase.co \
  --secret SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiJ9... \
  --path ./my-use-case

# JSON input (best for automation)
codika integration set anthropic \
  --secrets '{"ANTHROPIC_API_KEY":"sk-ant-xxx"}' \
  --json

# Custom integration — schema auto-extracted from config.ts
codika integration set cstm_acme_crm \
  --secret API_KEY=acme_sk_xxx \
  --path ./my-use-case \
  --json

# Custom integration — explicit schema file (fallback)
codika integration set cstm_acme_crm \
  --secret API_KEY=acme_sk_xxx \
  --custom-schema-file ./schema.json \
  --process-instance-id abc123

# Force overwrite
codika integration set openai \
  --secret OPENAI_API_KEY=sk-new-key \
  --force
```

### Custom integrations (cstm\_\*)

Custom integrations require a schema defining their fields and n8n credential mapping. The CLI resolves this schema automatically:

1. **Auto-extraction (recommended):** When `--path` points to a use case folder (or you run from one), the CLI reads `config.ts` and extracts the matching schema from the `customIntegrations` array. No separate file needed.
2. **Explicit file:** Pass `--custom-schema-file` with a JSON file containing the `CustomIntegrationSchema`.

### OAuth integrations

OAuth-based integrations (Gmail, Teams, Slack, etc.) cannot be configured from the CLI. The command will display the dashboard URL instead:

```
⚠ google_gmail requires OAuth authentication.
  Connect it via the dashboard at: https://app.codika.io/organizations/.../integrations
```

***

## `codika integration list`

Lists integrations and their connection status.

```bash theme={null}
codika integration list [options]
```

### Options

| Option                       | Description                          | Default             |
| ---------------------------- | ------------------------------------ | ------------------- |
| `--context-type <type>`      | `organization` or `process_instance` | `organization`      |
| `--process-instance-id <id>` | Process instance ID                  | From `project.json` |
| `--path <path>`              | Path to use case folder              | Current directory   |
| `--project-file <path>`      | Custom project file                  | `project.json`      |
| `--environment <env>`        | `dev` or `prod`                      | `dev`               |
| `--profile <name>`           | CLI profile to use                   | Active profile      |
| `--api-key <key>`            | Override API key                     | —                   |
| `--json`                     | Output as JSON                       | `false`             |

### Examples

```bash theme={null}
# List organization integrations
codika integration list

# List process instance integrations
codika integration list --context-type process_instance --path ./my-use-case

# JSON output
codika integration list --json
```

***

## `codika integration delete`

Deletes an integration. Uses two-phase deletion by default — first shows dependent processes, then deletes with `--confirm`.

```bash theme={null}
codika integration delete <integrationId> [options]
```

### Arguments

| Argument        | Description              |
| --------------- | ------------------------ |
| `integrationId` | Integration ID to delete |

### Options

| Option                       | Description                                     | Default             |
| ---------------------------- | ----------------------------------------------- | ------------------- |
| `--context-type <type>`      | `organization`, `member`, or `process_instance` | Auto-detected       |
| `--process-instance-id <id>` | Process instance ID                             | From `project.json` |
| `--path <path>`              | Path to use case folder                         | Current directory   |
| `--project-file <path>`      | Custom project file                             | `project.json`      |
| `--environment <env>`        | `dev` or `prod`                                 | `dev`               |
| `--confirm`                  | Skip confirmation and delete immediately        | `false`             |
| `--profile <name>`           | CLI profile to use                              | Active profile      |
| `--api-key <key>`            | Override API key                                | —                   |
| `--json`                     | Output as JSON                                  | `false`             |

### Examples

```bash theme={null}
# Check dependencies first
codika integration delete openai

# Delete immediately
codika integration delete openai --confirm

# Delete process instance integration
codika integration delete supabase \
  --confirm \
  --process-instance-id abc123
```

***

## `codika integration schema`

Fetches the n8n credential schema for a given credential type. Use this to discover which fields are required when creating a custom integration with any n8n credential type.

```bash theme={null}
codika integration schema <credentialType> [options]
```

### Arguments

| Argument         | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `credentialType` | n8n credential type (e.g., `twilioApi`, `openAiApi`, `httpHeaderAuth`) |

### Options

| Option             | Description            | Default        |
| ------------------ | ---------------------- | -------------- |
| `--profile <name>` | CLI profile to use     | Active profile |
| `--api-key <key>`  | Override API key       | —              |
| `--json`           | Output raw JSON schema | `false`        |

### Examples

```bash theme={null}
# See what fields twilioApi needs
codika integration schema twilioApi

# Output:
#   Credential type: twilioApi
#   Properties:
#     authType: string [authToken, apiKey]
#     accountSid: string
#     authToken: string
#     allowedDomains: string
#   Conditional rules:
#     if authType = authToken then require: authToken
#     if authType = apiKey then require: apiKeySid, apiKeySecret

# Raw JSON (for automation)
codika integration schema openAiApi --json
```

### Use with custom integrations

When you need a custom integration that maps to a specific n8n credential type (e.g., `twilioApi` instead of `httpHeaderAuth`), use `schema` to discover the required fields, then define your `n8nCredentialMapping` accordingly:

```bash theme={null}
# 1. Check what fields n8n needs
codika integration schema twilioApi

# 2. Define custom integration in config.ts with those fields
# n8nCredentialType: 'twilioApi'
# n8nCredentialMapping: { ACCOUNT_SID: 'accountSid', AUTH_TOKEN: 'authToken', ... }
```

***

## Common recipes

### Set up AI provider for an organization

```bash theme={null}
codika integration set openai \
  --secrets '{"OPENAI_API_KEY":"sk-proj-xxx"}' \
  --json
```

### Set up Supabase for a process instance

```bash theme={null}
codika integration set supabase \
  --secrets '{"SUPABASE_HOST":"https://abc.supabase.co","SUPABASE_SERVICE_ROLE_KEY":"eyJ..."}' \
  --path ./my-use-case \
  --json
```

### Full deployment + integration flow

```bash theme={null}
codika deploy use-case ./my-use-case --json
codika integration set openai --secrets '{"OPENAI_API_KEY":"sk-xxx"}' --json
codika integration set supabase \
  --secrets '{"SUPABASE_HOST":"...","SUPABASE_SERVICE_ROLE_KEY":"..."}' \
  --path ./my-use-case --json
# Custom integrations — schema auto-extracted from config.ts
codika integration set cstm_acme_crm \
  --secrets '{"API_KEY":"acme_sk_xxx"}' \
  --path ./my-use-case --json
codika rerun deployment --path ./my-use-case --force --json
```

## Authentication

All integration commands require an API key with the `integrations:manage` scope. The standard authentication chain applies:

1. `--api-key` flag (highest priority)
2. `CODIKA_API_KEY` environment variable
3. Active profile from `codika login`

## Exit codes

| Code | Meaning                                                                  |
| ---- | ------------------------------------------------------------------------ |
| `0`  | Success                                                                  |
| `1`  | API error                                                                |
| `2`  | Validation error (missing fields, OAuth integration, unconfirmed delete) |