---
title: "POST /v1/app-connections"
method: POST
path: "/v1/app-connections"
tags: ["app-connections"]
---

# POST /v1/app-connections

`POST /v1/app-connections`

Upsert an app connection based on the app name

## Request body

- union
  - object — Secret Text
    - `externalId` string, required
    - `displayName` string, required
    - `pieceName` string, required
    - `projectId` string, required
    - `type` 'SECRET_TEXT', required
    - `value` object, required
      - `type` 'SECRET_TEXT', required
      - `secret_text` string, required
  - object — OAuth2
    - `externalId` string, required
    - `displayName` string, required
    - `pieceName` string, required
    - `projectId` string, required
    - `type` 'OAUTH2', required
    - `value` object, required
      - `client_id` string, required
      - `code` string, required
      - `code_challenge` string
      - `scope` string, required
      - `authorization_method` union
        - 'HEADER'
        - 'BODY'
      - `client_secret` string, required
      - `grant_type` union
        - 'authorization_code'
        - 'client_credentials'
      - `props` object
      - `redirect_url` string, required
      - `type` 'OAUTH2', required
  - object — Cloud OAuth2
    - `externalId` string, required
    - `displayName` string, required
    - `pieceName` string, required
    - `projectId` string, required
    - `type` 'CLOUD_OAUTH2', required
    - `value` object, required
      - `client_id` string, required
      - `code` string, required
      - `code_challenge` string
      - `scope` string, required
      - `authorization_method` union
        - 'HEADER'
        - 'BODY'
      - `props` object
      - `type` 'CLOUD_OAUTH2', required
  - object — Platform OAuth2
    - `externalId` string, required
    - `displayName` string, required
    - `pieceName` string, required
    - `projectId` string, required
    - `type` 'PLATFORM_OAUTH2', required
    - `value` object, required
      - `client_id` string, required
      - `code` string, required
      - `code_challenge` string
      - `scope` string, required
      - `authorization_method` union
        - 'HEADER'
        - 'BODY'
      - `props` object
      - `type` 'PLATFORM_OAUTH2', required
      - `redirect_url` string, required
  - object — Basic Auth
    - `externalId` string, required
    - `displayName` string, required
    - `pieceName` string, required
    - `projectId` string, required
    - `type` 'BASIC_AUTH', required
    - `value` object, required
      - `username` string, required
      - `password` string, required
      - `type` 'BASIC_AUTH', required
  - object — Custom Auth
    - `externalId` string, required
    - `displayName` string, required
    - `pieceName` string, required
    - `projectId` string, required
    - `type` 'CUSTOM_AUTH', required
    - `value` object, required
      - `type` 'CUSTOM_AUTH', required
      - `props` object, required

## Response `200`

Default Response

## Changes

- **2024-11-12** `499ae054e9e9` — 12 breaking, 6 warning
  - added the new required request property `anyOf[subschema #1: Secret Text]/displayName`
  - added the new required request property `anyOf[subschema #1: Secret Text]/externalId`
  - added the new required request property `anyOf[subschema #2: OAuth2]/displayName`
  - added the new required request property `anyOf[subschema #2: OAuth2]/externalId`
  - …14 more
- **2024-09-13** `225ff954244e` — 1 breaking, 1 info
  - api path removed without deprecation
  - endpoint added
- **2024-09-05** `3e19fa5e716a` — 12 breaking
  - the `anyOf[subschema #1: Secret Text]/value/secret_text` request property's minLength was increased from `0` to `1`
  - the `anyOf[subschema #2: OAuth2]/value/client_id` request property's minLength was increased from `0` to `1`
  - the `anyOf[subschema #2: OAuth2]/value/client_secret` request property's minLength was increased from `0` to `1`
  - the `anyOf[subschema #2: OAuth2]/value/code` request property's minLength was increased from `0` to `1`
  - …8 more
- **2024-02-22** `b8aa27750656` — 3 warning, 1 info
  - removed the request property `anyOf[subschema #2: OAuth2]/value/token_url`
  - removed the request property `anyOf[subschema #3: Cloud OAuth2]/value/token_url`
  - removed the request property `anyOf[subschema #4: Platform OAuth2]/value/token_url`
  - the endpoint scheme security `apiKey` was added to the API
- …earlier changes not shown

[Full history](https://skmtc.dev/activeboxes/apis/activeboxes-documentation/changes/v1/app-connections/post.md)

---

[API](https://skmtc.dev/activeboxes/apis/activeboxes-documentation.md) · [All operations](https://skmtc.dev/activeboxes/apis/activeboxes-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/activeboxes/activeboxes-documentation/revisions/12c564515962/schema)