Settings

Create an SSO connection

Changed on

Creates a connection, switched off for both roles. Register its callbackUrl at the provider, run a test from the dashboard, then switch it on for candidates or employers with PATCH. Leave out issuer and clientId to create a draft and get its callbackUrl first; set them with PATCH before testing. The request is idempotent when an Idempotency-Key header is supplied.

post/sso-connections

Request

  • Base URL: https://api.cavuno.com/v1
  • URL: https://api.cavuno.com/v1/sso-connections
  • Auth: HTTP bearer

Request body

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.

issuerstring

The provider issuer URL. Every sign-in must come from this issuer; it identifies linked identities. May be left out to create a draft, which cannot be tested until it is set.

discoveryUrlstring nullable

OpenID Connect discovery URL. Defaults to {issuer}/.well-known/openid-configuration.

authorizationEndpointstring nullable

Authorization URL. Required for oauth2_userinfo.

tokenEndpointstring nullable

Token URL. Required for oauth2_userinfo.

userinfoEndpointstring nullable

Userinfo URL. Required for oauth2_userinfo.

jwksUristring nullable

JWKS URL, when the discovery document does not name one.

scopesstring[] nullable

Scopes requested from the provider.

clientIdstring

The client ID registered at the provider. May be left out to create a draft, which cannot be tested until it is set.

clientSecretstring 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.

labelstring required

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.

trustedProviderEmailboolean

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.

Response

Successful response.

idstring required

Unique identifier for the SSO connection.

object'sso_connection' required
protocol'oidc' | 'oauth2_userinfo' | 'saml' required
labelstring 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.

issuerstring 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.

discoveryUrlstring nullable required
authorizationEndpointstring nullable required
tokenEndpointstring nullable required
userinfoEndpointstring nullable required
jwksUristring nullable required
scopesstring[] nullable required
clientIdstring required

The client ID; empty on a draft not set up yet.

hasClientSecretboolean required

Whether a client secret is stored. The secret is never returned.

trustedProviderEmailboolean 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.

offeredToCandidatesboolean required

Whether candidates can sign in with this connection.

offeredToEmployersboolean required

Whether employers can sign in with this connection.

liveConfigTestedboolean required

A test passed on the live settings, so the connection can be switched on. Until then both switches stay off.

callbackUrlstring required

The redirect URL to register at the provider.

lastTestPassedAtstring nullable required
createdAtstring required
updatedAtstring required

Changes

  • c34152c38176Revision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status