Sso Settings Api Update Sso Settings
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.
The complete Enterprise SSO configuration, which replaces the saved one. The client secret is write-only and is never returned.
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
}
Whether Enterprise SSO is enabled; enabling needs an effective external base URL (externalBaseUrl or the appliance default), issuerUri and clientId
Text for the 'Sign in with ...' button
External base URL: https, no userinfo, path, query or fragment; otherwise 400 INVALID_EXTERNAL_BASE_URL
OIDC issuer URI (https, no user info, query or fragment); a saved issuer cannot be cleared
OIDC client identifier
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.
Space-separated OIDC scopes
Name of the ID-token claim carrying groups
Absent keeps the current value (60 when never set); a value outside 0..300 is 400 INVALID_CLOCK_SKEW
Role for users with no mapped group; null or absent means deny. ADMIN is rejected with 400 DEFAULT_ROLE_NOT_ALLOWED.
Set to true to confirm an issuer change after the 409 ISSUER_CHANGE_CONFIRMATION_REQUIRED warning
200 OK successful response envelope. The saved configuration after the replace
{
"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"
}
Whether Enterprise SSO is enabled
Text for the 'Sign in with ...' button
Administrator-configured external base URL: https, no userinfo, path, query or fragment
OIDC issuer URI (https)
OIDC client identifier
True when a client secret is stored; the secret itself is never returned
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
Space-separated OIDC scopes
Name of the ID-token claim carrying groups
Tolerated clock difference in seconds between the console and the IdP; default 60, maximum 300
Role for users with no mapped group; unset means such users are denied
Timestamp of the last update as an ISO 8601 date-time with offset
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.
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 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
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 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)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Conflict error response (ISSUER_CHANGE_CONFIRMATION_REQUIRED; nothing saved)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
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 Service Unavailable error response (SSO_KEY_UNAVAILABLE; nothing saved)
"ApiErrorResponse Object"
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.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
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