---
title: "Create or update an OAuth integration connection for the signed-in user."
method: PUT
path: "/v1/integrations/{name}"
tags: ["integrations"]
---

# Create or update an OAuth integration connection for the signed-in user.

`PUT /v1/integrations/{name}`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/integrations/{name}`
- Auth: HTTP bearer

Create or update an OAuth integration connection for the signed-in user. Names are normalized to a canonical lowercase-kebab provider key. Partial updates merge into the existing connection; matching client credentials reuse a shared OAuth app across connections. Do not persist access or refresh tokens here or with secretSet — `/connect/oauth` and `integrationTokenRefresh` write those on the connection. authorization.scopes is reconnect metadata: the list the next /connect/oauth visit requests, not the current access token. After widening scopes, tell the user the token is unchanged until they reconnect, then ask whether to reconnect each affected account at /connect/oauth?provider=<connection-name>. Scopes are per connection; sibling accounts that share an OAuth app keep their own lists. This capability cannot change usageMode or add requiredHosts / retarget tokenUrl to an unapproved host. Platform (built-in) connections cannot be updated here — reconnect at /connect/oauth?provider=<name> to change scopes, or integrationDelete first to replace with a bring-your-own app.

Org permission: `integration:write`.

## Path parameters

- `name` string, required

## Request body

- object
  - `tokenUrl` string, uri
  - `apiBaseUrl` string, uri, nullable
  - `flow` 'pkce' | 'confidential' | 'device'
  - `usePkce` boolean, nullable
  - `clientId` string
  - `requiredHosts` string[]
  - `tokenExchangeStyle` 'form' | 'basic-json' | 'basic-form', nullable
  - `deviceAuthorizationUrl` string, uri, nullable
  - `authorization` object, nullable
    - `authorizeUrl` string, uri, required
    - `scopes` string[], required
    - `scopeSeparator` string, nullable
    - `extraAuthorizeParams` object
  - `accountLabel` string, nullable
  - `logoBase64` string, nullable: Base64-encoded OAuth app logo (SVG, PNG, JPEG, or WebP). Kody fits the image to 256px WebP before storage. Omit to keep the current logo, pass null to clear it and re-fetch the provider favicon.

## Response `200`

Success.

- object
  - `integration` object, required
    - `name` string, required
    - `tokenUrl` string, uri, required
    - `apiBaseUrl` string, uri, nullable
    - `flow` 'pkce' | 'confidential' | 'device', required
    - `usePkce` boolean, nullable
    - `clientId` string, required
    - `requiredHosts` string[]
    - `tokenExchangeStyle` 'form' | 'basic-json' | 'basic-form', nullable
    - `deviceAuthorizationUrl` string, uri, nullable
    - `authorization` object, nullable
      - `authorizeUrl` string, uri, required
      - `scopes` string[], required
      - `scopeSeparator` string, nullable
      - `extraAuthorizeParams` object
    - `platform` boolean
    - `usageMode` 'any' | 'packages'
    - `allowedPackageIds` string[]
    - `credentialId` string
    - `lastAuthFailure` object
      - `reason` 'missing_refresh_token' | 'provider_rejected' | 'missing_secret' | 'host_not_approved' | 'invalid_config' | 'provider_unavailable', required
      - `occurredAt` string, required
      - `reconnectable` boolean, required
      - `providerError` string, nullable, required
      - `providerErrorDescription` string, nullable, required
      - `httpStatus` integer, nullable, required
      - `title` string, required
      - `why` string, required
      - `who` 'you' | 'kody' | 'the-service', required
      - `doLabel` string, required
      - `reconnectHref` string, required
      - `accountHref` string, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)