---
title: "Update an SSO connection"
method: PATCH
path: "/sso-connections/{id}"
tags: ["Settings"]
---

# Update an SSO connection

`PATCH /sso-connections/{id}`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/sso-connections/{id}`
- Auth: HTTP bearer

Updates the fields sent; `null` clears an optional field. On a connection that has passed a test, changes to provider settings wait in `pendingChanges` until a test passes on them and they are saved in the dashboard. Label, role switches, provisioning and trusted email apply at once.

## Path parameters

- `id` string, required: The SSO connection ID returned by create or list endpoints.

## Request body

- UpdateSsoConnectionBody
  - `protocol` 'oidc' | 'oauth2_userinfo': `oidc` for OpenID Connect providers (discovery and ID tokens); `oauth2_userinfo` for OAuth 2.0 providers that expose a userinfo endpoint instead.
  - `issuer` string: The provider issuer URL. Every sign-in must come from this issuer; it identifies linked identities.
  - `discoveryUrl` string, nullable: OpenID Connect discovery URL. Defaults to `{issuer}/.well-known/openid-configuration`.
  - `authorizationEndpoint` string, nullable: Authorization URL. Required for `oauth2_userinfo`.
  - `tokenEndpoint` string, nullable: Token URL. Required for `oauth2_userinfo`.
  - `userinfoEndpoint` string, nullable: Userinfo URL. Required for `oauth2_userinfo`.
  - `jwksUri` string, nullable: JWKS URL, when the discovery document does not name one.
  - `scopes` string[], nullable: Scopes requested from the provider.
  - `clientId` string: The client ID registered at the provider.
  - `clientSecret` string, nullable: The client secret. Write-only: stored encrypted and never returned. On update, omit it to keep the stored secret or send `null` to remove it.
  - `claimNames` object, nullable: Where to read identity from in the provider response.
    - `subject` string, nullable: Claim holding the stable member ID. Defaults to `sub`.
    - `email` string, nullable: Claim holding the email. Defaults to `email`.
    - `emailVerified` string, nullable: Claim saying whether the email is verified. Defaults to `email_verified`.
    - `displayName` string, nullable: Claim holding the display name. Defaults to `name`.
  - `label` string: The text on the sign-in button.
  - `provider` 'okta' | 'generic_oidc' | 'generic_oauth2': The identity provider the connection is for: `okta`, or `generic_oidc` / `generic_oauth2` for any other provider that supports OpenID Connect or OAuth 2.0. Only used to name the provider in the dashboard’s setup steps; it does not change how sign-in works.
  - `trustedProviderEmail` boolean: Sign someone straight into the existing board account with the same verified email, without a confirmation email. Only enable when the provider alone controls who has each email.
  - `provisioning` 'auto_create' | 'pre_provisioned_only': `auto_create` creates a board account on first sign-in; `pre_provisioned_only` signs in only people who already have one.
  - `candidateSignInMode` 'off' | 'available' | 'required': Deprecated: use per-role connection switches and settings.signInMethods instead.
  - `employerSignInMode` 'off' | 'available' | 'required': Deprecated: use per-role connection switches and settings.signInMethods instead.
  - `offeredToCandidates` boolean: Switch the connection on or off for candidates. Switching on needs a passing test on the live settings (409 `sso_connections_untested`); switching off is refused while it is the only way candidates can sign in (409 `sign_in_method_last`).
  - `offeredToEmployers` boolean: Switch the connection on or off for employers, with the same rules as `offeredToCandidates`.

## Response `200`

Successful response.

- SsoConnection
  - `id` string, required: Unique identifier for the SSO connection.
  - `object` 'sso_connection', required
  - `protocol` 'oidc' | 'oauth2_userinfo' | 'saml', required
  - `label` string, required
  - `provider` 'okta' | 'generic_oidc' | 'generic_oauth2', nullable, required: The identity provider the connection is for: `okta`, or `generic_oidc` / `generic_oauth2` for any other provider that supports OpenID Connect or OAuth 2.0. Only used to name the provider in the dashboard’s setup steps; it does not change how sign-in works.
  - `issuer` string, required: The provider issuer URL; empty on a draft not set up yet.
  - `status` 'draft' | 'tested' | 'enabled' | 'disabled', required: Deprecated: use liveConfigTested and offeredToCandidates/offeredToEmployers.
  - `candidateSignInMode` 'off' | 'available' | 'required', required: Deprecated: use per-role connection switches and settings.signInMethods instead.
  - `employerSignInMode` 'off' | 'available' | 'required', required: Deprecated: use per-role connection switches and settings.signInMethods instead.
  - `discoveryUrl` string, nullable, required
  - `authorizationEndpoint` string, nullable, required
  - `tokenEndpoint` string, nullable, required
  - `userinfoEndpoint` string, nullable, required
  - `jwksUri` string, nullable, required
  - `scopes` string[], nullable, required
  - `clientId` string, required: The client ID; empty on a draft not set up yet.
  - `hasClientSecret` boolean, required: Whether a client secret is stored. The secret is never returned.
  - `claimNames` SsoConnectionClaimNames, nullable, required
    - `subject` string, nullable: Claim holding the stable member ID. Defaults to `sub`.
    - `email` string, nullable: Claim holding the email. Defaults to `email`.
    - `emailVerified` string, nullable: Claim saying whether the email is verified. Defaults to `email_verified`.
    - `displayName` string, nullable: Claim holding the display name. Defaults to `name`.
  - `trustedProviderEmail` boolean, required
  - `provisioning` 'auto_create' | 'pre_provisioned_only', required: `auto_create` creates a board account on first sign-in; `pre_provisioned_only` signs in only people who already have one.
  - `offeredToCandidates` boolean, required: Whether candidates can sign in with this connection.
  - `offeredToEmployers` boolean, required: Whether employers can sign in with this connection.
  - `liveConfigTested` boolean, required: A test passed on the live settings, so the connection can be switched on. Until then both switches stay off.
  - `pendingChanges` SsoConnectionPendingChanges, nullable, required: Settings edits on a tested connection wait here until a test passes on them and they are saved in the dashboard; sign-ins keep using the live settings meanwhile.
    - `protocol` 'oidc' | 'oauth2_userinfo', required: `oidc` for OpenID Connect providers (discovery and ID tokens); `oauth2_userinfo` for OAuth 2.0 providers that expose a userinfo endpoint instead.
    - `issuer` string, required
    - `discoveryUrl` string, nullable, required
    - `authorizationEndpoint` string, nullable, required
    - `tokenEndpoint` string, nullable, required
    - `userinfoEndpoint` string, nullable, required
    - `jwksUri` string, nullable, required
    - `scopes` string[], nullable, required
    - `clientId` string, required
    - `hasClientSecret` boolean, required
    - `claimNames` SsoConnectionClaimNames, nullable, required
      - `subject` string, nullable: Claim holding the stable member ID. Defaults to `sub`.
      - `email` string, nullable: Claim holding the email. Defaults to `email`.
      - `emailVerified` string, nullable: Claim saying whether the email is verified. Defaults to `email_verified`.
      - `displayName` string, nullable: Claim holding the display name. Defaults to `name`.
  - `callbackUrl` string, required: The redirect URL to register at the provider.
  - `lastTestPassedAt` string, nullable, required
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `400`: A field is invalid.
- `404`: SSO connection not found.
- `409`: A role switch was refused: the connection has not passed a test, or it is the only way that role can sign in.

## Changes

- **2026-10-19** `c34152c38176`: 3 info
  - added the optional property `error/upgrade` to the response with the `400` status
  - added the optional property `error/upgrade` to the response with the `404` status
  - added the optional property `error/upgrade` to the response with the `409` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/sso-connections/:id/patch.md)

---

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