---
title: "CreateIntegration"
method: POST
path: "/gitpod.v1.IntegrationService/CreateIntegration"
tags: ["gitpod.v1.IntegrationService"]
---

# CreateIntegration

`POST /gitpod.v1.IntegrationService/CreateIntegration`

Creates a new integration instance within an organization.

 Use this method to:
 - Instantiate an integration for an organization
 - Configure integration-specific settings
 - Enable integration capabilities

## Request body

- GitpodV1CreateIntegrationRequest
  - `auth` GitpodV1IntegrationAuthentication — IntegrationAuthentication defines authentication requirements and options
    - `apiKey` GitpodV1IntegrationAPIKeyConfig — IntegrationAPIKeyConfig defines API key authentication configuration Additional API key configuration can be added here
    - `oauth` GitpodV1IntegrationOAuthConfig — IntegrationOAuthConfig defines OAuth-specific configuration
      - `authUrl` string — auth_url is the OAuth authorization endpoint URL
      - `clientId` string — client_id is the OAuth client ID (optional if dynamic_registration is enabled)
      - `clientSecret` string — client_secret is the OAuth client secret (optional for public clients)
      - `dynamicRegistration` boolean — dynamic_registration enables RFC 7591 OAuth 2.0 Dynamic Client Registration. When enabled, client credentials are obtained automatically from the authorization server's registration endpoint (discovered via RFC 8414 metadata). When disabled (default), client_id and client_secret must be pre-configured.
      - `redirectUrl` string — redirect_url is the OAuth callback/redirect URL
      - `scopes` string[] — scopes are the OAuth scopes to request
      - `tokenUrl` string — token_url is the OAuth token endpoint URL
    - `proprietaryApp` GitpodV1IntegrationProprietaryAppConfig — IntegrationProprietaryAppConfig defines proprietary application integration configuration. Used for app installations that interact with Ona (e.g., GitHub Apps, Linear agent apps).
      - `appScopes` string[] — app_scopes are OAuth scopes to request when using app installation flows. If not set, falls back to the standard OAuth scopes.
      - `authParams` object — auth_params are additional OAuth authorization parameters to include in the auth URL. Example: {"actor": "app"} for Linear agent installations.
      - `clientId` string — client_id is the app client ID
      - `clientSecret` string — client_secret is the app client secret
      - `webhookSecret` string — webhook_secret is the secret used to verify webhook signatures from the app provider
    - `requiresAuth` boolean — requires_auth indicates if authentication is required for this integration
  - `capabilities` GitpodV1IntegrationCapabilities — IntegrationCapabilities defines what an integration can do
    - `agentClient` GitpodV1IntegrationAgentClientCapability — IntegrationAgentClientCapability indicates the integration supports agent client functionality. The webhook signing secret is stored in IntegrationProprietaryAppConfig.webhook_secret. Empty - presence of this capability indicates agent client support
    - `contextParsing` GitpodV1IntegrationContextParsingCapability — IntegrationContextParsingCapability defines context parsing capability Additional context parsing configuration can be added here
    - `login` GitpodV1IntegrationLoginCapability — IntegrationLoginCapability defines login/authentication capability Additional login configuration can be added here
    - `mcp` GitpodV1IntegrationMCPCapability — IntegrationMCPCapability defines Model Context Protocol capability
      - `url` string — url is the remote server URL for the MCP server
    - `sourceCodeAccess` GitpodV1IntegrationSourceCodeAccessCapability — IntegrationSourceCodeAccessCapability defines source code access capability Additional source code access configuration can be added here
  - `enabled` boolean — enabled indicates if this integration is enabled
  - `host` string — host is the hostname for this integration (e.g., "linear.app") - optional, inherits from definition
  - `integrationDefinitionId` string — integration_definition_id references the integration definition ID
  - `runnerId` string, uuid — runner_id is optional and immutable - if provided, restricts integration to specific runner

## Response `200`

Success

- GitpodV1CreateIntegrationResponse
  - `integration` GitpodV1Integration, required — Integration represents an instantiated integration within an organization
    - `auth` GitpodV1IntegrationAuthentication — IntegrationAuthentication defines authentication requirements and options
      - `apiKey` GitpodV1IntegrationAPIKeyConfig — IntegrationAPIKeyConfig defines API key authentication configuration Additional API key configuration can be added here
      - `oauth` GitpodV1IntegrationOAuthConfig — IntegrationOAuthConfig defines OAuth-specific configuration
        - `authUrl` string — auth_url is the OAuth authorization endpoint URL
        - `clientId` string — client_id is the OAuth client ID (optional if dynamic_registration is enabled)
        - `clientSecret` string — client_secret is the OAuth client secret (optional for public clients)
        - `dynamicRegistration` boolean — dynamic_registration enables RFC 7591 OAuth 2.0 Dynamic Client Registration. When enabled, client credentials are obtained automatically from the authorization server's registration endpoint (discovered via RFC 8414 metadata). When disabled (default), client_id and client_secret must be pre-configured.
        - `redirectUrl` string — redirect_url is the OAuth callback/redirect URL
        - `scopes` string[] — scopes are the OAuth scopes to request
        - `tokenUrl` string — token_url is the OAuth token endpoint URL
      - `proprietaryApp` GitpodV1IntegrationProprietaryAppConfig — IntegrationProprietaryAppConfig defines proprietary application integration configuration. Used for app installations that interact with Ona (e.g., GitHub Apps, Linear agent apps).
        - `appScopes` string[] — app_scopes are OAuth scopes to request when using app installation flows. If not set, falls back to the standard OAuth scopes.
        - `authParams` object — auth_params are additional OAuth authorization parameters to include in the auth URL. Example: {"actor": "app"} for Linear agent installations.
        - `clientId` string — client_id is the app client ID
        - `clientSecret` string — client_secret is the app client secret
        - `webhookSecret` string — webhook_secret is the secret used to verify webhook signatures from the app provider
      - `requiresAuth` boolean — requires_auth indicates if authentication is required for this integration
    - `capabilities` GitpodV1IntegrationCapabilities — IntegrationCapabilities defines what an integration can do
      - `agentClient` GitpodV1IntegrationAgentClientCapability — IntegrationAgentClientCapability indicates the integration supports agent client functionality. The webhook signing secret is stored in IntegrationProprietaryAppConfig.webhook_secret. Empty - presence of this capability indicates agent client support
      - `contextParsing` GitpodV1IntegrationContextParsingCapability — IntegrationContextParsingCapability defines context parsing capability Additional context parsing configuration can be added here
      - `login` GitpodV1IntegrationLoginCapability — IntegrationLoginCapability defines login/authentication capability Additional login configuration can be added here
      - `mcp` GitpodV1IntegrationMCPCapability — IntegrationMCPCapability defines Model Context Protocol capability
        - `url` string — url is the remote server URL for the MCP server
      - `sourceCodeAccess` GitpodV1IntegrationSourceCodeAccessCapability — IntegrationSourceCodeAccessCapability defines source code access capability Additional source code access configuration can be added here
    - `enabled` boolean — enabled indicates if this integration is currently enabled
    - `host` string — host is the hostname for this integration (e.g., "linear.app") - optional, inherits from definition
    - `id` string, required — id is the unique identifier for this integration instance
    - `integrationDefinitionId` string, required — integration_definition_id references the integration definition ID
    - `organizationId` string, required — organization_id is the organization this integration belongs to
    - `runnerId` string — runner_id - if set, restricts integration to specific runner

## Other responses

- `default` — Error

## Changes

- **2026-02-11** `b97dcde84128` — 2 warning, 4 info
  - removed the request property `capabilities/mcp/headers`
  - removed the optional property `integration/capabilities/mcp/headers` from the response with the `200` status
  - added the new optional request property `auth/proprietaryApp/appScopes`
  - added the new optional request property `auth/proprietaryApp/authParams`
  - …2 more
- **2026-01-09** `3935e467f9c1` — 2 info
  - added the new optional request property `auth/oauth/dynamicRegistration`
  - added the optional property `integration/auth/oauth/dynamicRegistration` to the response with the `200` status
- **2025-12-15** `d62ef4b9187c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.IntegrationService/CreateIntegration/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/b97dcde84128/schema)