Sso Settings Api Update Sso Settings

Sso Settings Api Update Sso Settings
Update Enterprise SSO settings (Administrator only)

A full replace. The ApiErrorResponse errorCode is one of: 400 INVALID_EXTERNAL_BASE_URL, EXTERNAL_BASE_URL_REQUIRED, DEFAULT_ROLE_NOT_ALLOWED, INVALID_CLOCK_SKEW, CLIENT_SECRET_REQUIRED_FOR_ISSUER_CHANGE and VALIDATION_FAILED; 409 ISSUER_CHANGE_CONFIRMATION_REQUIRED; 503 SSO_KEY_UNAVAILABLE (the master key is missing or unreadable while a client secret must be encrypted; nothing is saved). Disabling SSO or a confirmed issuer change revokes all active SSO sessions in the same transaction, including the acting administrator's own; the revocation audit reason is SSO_DISABLED or ISSUER_CHANGED respectively.

Request
URI
PUT
https://{api_host}/api/v1/settings/sso
COPY
Request Body

The complete Enterprise SSO configuration, which replaces the saved one. The client secret is write-only and is never returned.

SsoSettingsUpdateRequest of type(s) application/json
Required  

Show optional properties

{
    "enabled": false,
    "displayName": "string",
    "scopes": "string",
    "groupsClaim": "string"
}
{
    "enabled": true,
    "displayName": "Example Corp SSO",
    "externalBaseUrl": "https://console.example.com",
    "issuerUri": "https://idp.example.com/realms/example",
    "clientId": "vtp-console",
    "clientSecret": "<redacted>",
    "scopes": "openid profile email",
    "groupsClaim": "groups",
    "clockSkewSeconds": 120,
    "defaultRole": "SECURITY_OPERATOR",
    "confirmIssuerChange": false
}
boolean
enabled
Required  

Whether Enterprise SSO is enabled; enabling needs an effective external base URL (externalBaseUrl or the appliance default), issuerUri and clientId

string
displayName
Required  
Constraints: minLength: 1 maxLength: 64

Text for the 'Sign in with ...' button

string
externalBaseUrl
Optional
Constraints: maxLength: 2048

External base URL: https, no userinfo, path, query or fragment; otherwise 400 INVALID_EXTERNAL_BASE_URL

string
issuerUri
Optional
Constraints: maxLength: 2048

OIDC issuer URI (https, no user info, query or fragment); a saved issuer cannot be cleared

string
clientId
Optional
Constraints: maxLength: 512

OIDC client identifier

string
clientSecret
Optional
Constraints: maxLength: 4096

Client secret, input only. Omit or send blank to keep the stored secret; it can never be cleared. Never present in any response, log or audit record.

string
scopes
Required  
Constraints: maxLength: 1024

Space-separated OIDC scopes

string
groupsClaim
Required  
Constraints: maxLength: 256

Name of the ID-token claim carrying groups

integer As int32 As int32
clockSkewSeconds
Optional
Constraints: minimum: 0 maximum: 300

Absent keeps the current value (60 when never set); a value outside 0..300 is 400 INVALID_CLOCK_SKEW

defaultRole
Optional

Role for users with no mapped group; null or absent means deny. ADMIN is rejected with 400 DEFAULT_ROLE_NOT_ALLOWED.

boolean
confirmIssuerChange
Optional

Set to true to confirm an issuer change after the 409 ISSUER_CHANGE_CONFIRMATION_REQUIRED warning

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The saved configuration after the replace

Returns SsoSettingsResponse of type(s) application/json
{
    "enabled": true,
    "displayName": "Example Corp SSO",
    "externalBaseUrl": "https://console.example.com",
    "issuerUri": "https://idp.example.com/realms/example",
    "clientId": "vtp-console",
    "clientSecretStored": true,
    "clientSecretReenterRequired": false,
    "scopes": "openid profile email",
    "groupsClaim": "groups",
    "clockSkewSeconds": 120,
    "defaultRole": "SECURITY_OPERATOR",
    "updatedAt": "2026-01-15T09:30:00Z",
    "effectiveExternalBaseUrl": "https://console.example.com",
    "externalBaseUrlSource": "SETTINGS"
}
boolean
enabled
Required  

Whether Enterprise SSO is enabled

string
displayName
Required  

Text for the 'Sign in with ...' button

string
externalBaseUrl
Optional

Administrator-configured external base URL: https, no userinfo, path, query or fragment

string
issuerUri
Optional

OIDC issuer URI (https)

string
clientId
Optional

OIDC client identifier

boolean
clientSecretStored
Required  

True when a client secret is stored; the secret itself is never returned

boolean
clientSecretReenterRequired
Required  

True when a secret is stored but its key id differs from the current key id or the current key id cannot be obtained; the administrator must re-enter it

string
scopes
Required  

Space-separated OIDC scopes

string
groupsClaim
Required  

Name of the ID-token claim carrying groups

integer As int32 As int32
clockSkewSeconds
Required  

Tolerated clock difference in seconds between the console and the IdP; default 60, maximum 300

defaultRole
Optional

Role for users with no mapped group; unset means such users are denied

string As date-time As date-time
updatedAt
Optional

Timestamp of the last update as an ISO 8601 date-time with offset

string
effectiveExternalBaseUrl
Required   Read-Only  

Read-only. The external base URL the console uses to build the OIDC redirect URI - the saved externalBaseUrl when non-blank, otherwise the appliance default, otherwise null. Never derived from request headers.

externalBaseUrlSource
Required   Read-Only  

Read-only. SETTINGS when a saved externalBaseUrl is in effect, APPLIANCE_DEFAULT when the operator-set default is in effect, NONE when neither exists.


400

400 Bad Request: VALIDATION_FAILED when displayName is blank or too long, another field is too long, issuerUri is not a plain https URL or is cleared after one was saved, or SSO is enabled without issuerUri or clientId; INVALID_EXTERNAL_BASE_URL when externalBaseUrl is not an https URL with only a host; EXTERNAL_BASE_URL_REQUIRED when SSO is enabled with no externalBaseUrl and no configured default; DEFAULT_ROLE_NOT_ALLOWED when defaultRole is ADMIN; INVALID_CLOCK_SKEW when clockSkewSeconds is outside 0 to 300; CLIENT_SECRET_REQUIRED_FOR_ISSUER_CHANGE when the issuer changes and no clientSecret is supplied; MALFORMED_REQUEST when the body cannot be read

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN when the signed-in role is not allowed to call this operation; CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ForbiddenWrite of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict error response (ISSUER_CHANGE_CONFIRMATION_REQUIRED; nothing saved)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


503

503 Service Unavailable error response (SSO_KEY_UNAVAILABLE; nothing saved)

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X PUT -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"enabled":"boolean","displayName":"string","scopes":"string","groupsClaim":"string"}' https://{api_host}/api/v1/settings/sso