Skip to content
You're viewing documentation for v2026.11.11-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview

Set single sign-on settings

Applies at once, with no restart. When a save turns SSO on or changes the issuer URL, the client ID or the client secret, the console must read the discovery document of the issuer, and the client secret must be readable. Other saves do not contact the identity provider. An empty client_secret keeps the stored secret, also one that is unreadable. Local login can be off only while SSO is on, and to turn SSO off turns local login on. Only an SSO session or the admin token can turn local login off; that ends the sessions of the local users.

PUT/api/v1/settings/oidc
Authorization
tse_sessionAPI key · cookierequired
Request body
requiredapplication/json
admin_groupsstring[]
allow_local_loginbooleanrequired

To turn SSO off turns local login on

client_idstring
client_secretstring

Empty keeps the stored secret

default_rolestring

none, viewer, operator or admin

enabledbooleanrequired
issuer_urlstring
operator_groupsstring[]
role_claimstring

Empty: groups

viewer_groupsstring[]
Responses
200

OK

admin_groupsstring[]required
allow_local_loginbooleanrequired

Local users can log in with a password. Off only while SSO is on

client_idstringrequired
client_secret_statestringrequired

The stored client secret: set, unset, or unreadable (it does not decrypt with the current TSE_DB_ENCRYPTION_KEY: enter it again). The API never returns the secret.

Allowed:setunsetunreadable
default_rolestringrequired

The role of a user with no matching group. none: the user can log in only with a service grant

Allowed:nonevieweroperatoradmin
enabledbooleanrequired

SSO is on: the login page shows Log in with SSO

issuer_urlstringrequired
local_login_lock_reasonstringrequired

Why this session cannot turn local login off, or empty

operator_groupsstring[]required
redirect_uristringrequired

The redirect URI to register at the identity provider

role_claimstringrequired

The ID token claim that holds the groups

viewer_groupsstring[]required
default

Error

codestring

Stable code of the refusal, when the route has codes

detailsstring[]

Additional detail, e.g. per-field validation failures

errorstringrequired

Human-readable error message

Request
curl -X PUT 'https://console.example.com/api/v1/settings/oidc' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "admin_groups": [
    "string"
  ],
  "allow_local_login": true,
  "client_id": "string",
  "client_secret": "string",
  "default_role": "string",
  "enabled": true,
  "issuer_url": "string",
  "operator_groups": [
    "string"
  ],
  "role_claim": "string",
  "viewer_groups": [
    "string"
  ]
}'
Response
{
  "admin_groups": [
    "string"
  ],
  "allow_local_login": true,
  "client_id": "string",
  "client_secret_state": "set",
  "default_role": "none",
  "enabled": true,
  "issuer_url": "string",
  "local_login_lock_reason": "string",
  "operator_groups": [
    "string"
  ],
  "redirect_uri": "string",
  "role_claim": "string",
  "viewer_groups": [
    "string"
  ]
}