---
title: "Create or replace the SSO connection (Enterprise plan). Signed-in workspace admins only; API keys get 403. Enabling it checks the provider's discovery document first."
method: PUT
path: "/api/v1/sso"
tags: ["Single sign-on"]
---

# Create or replace the SSO connection (Enterprise plan). Signed-in workspace admins only; API keys get 403. Enabling it checks the provider's discovery document first.

`PUT /api/v1/sso`

## Request

- Base URL: `https://qrlia.dev.castlesoft.eu`
- URL: `https://qrlia.dev.castlesoft.eu/api/v1/sso`
- Auth: API key in cookie `qrc_session`

## Request body

- object
  - `issuer` string, uri, required: OpenID Connect issuer URL, e.g. https://accounts.google.com, https://login.microsoftonline.com/<tenant-id>/v2.0 or https://<org>.okta.com. Must serve /.well-known/openid-configuration.
  - `clientId` string, required
  - `clientSecret` string: Write-only. Required when creating the connection; omit to keep the stored secret.
  - `allowedDomains` string[], required: Email domains the identity provider may sign in, e.g. ["example.com"].
  - `enabled` boolean: Show the SSO button and accept SSO sign-ins.
  - `enforced` boolean: Turn off password sign-in for everyone except workspace admins (who keep it as a fallback).
  - `autoProvision` boolean: Create an account on first SSO sign-in for allowed-domain users who don't have one yet.
  - `defaultRole` 'advanced' | 'limited': Role given to accounts created on first SSO sign-in. Owner is never granted automatically.
  - `trustUnverifiedEmail` boolean: Accept sign-ins whose email the provider doesn't mark verified. Needed for Microsoft Entra ID, which never sends email_verified; only turn on for a provider whose directory you control.
  - `buttonLabel` string, nullable: Login button text, e.g. "Sign in with Okta". Defaults to "Sign in with SSO".

## Response `200`

Saved

- object
  - `connection` SsoConnection, required
    - `issuer` string, required
    - `clientId` string, required
    - `clientSecretSet` true, required
    - `allowedDomains` string[], required
    - `enabled` boolean, required
    - `enforced` boolean, required
    - `autoProvision` boolean, required
    - `defaultRole` 'advanced' | 'limited', required: Role given to accounts created on first SSO sign-in. Owner is never granted automatically.
    - `trustUnverifiedEmail` boolean, required
    - `buttonLabel` string, nullable, required
    - `redirectUris` string[], required: Register every one of these as an allowed redirect / callback URL at the identity provider.
    - `lastLoginAt` string, date-time, nullable, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Validation failed
- `401`: Authentication required
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict
- `500`: Internal

---

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