System Settings

Configure system-wide settings for languages, OIDC, and security

System settings endpoints allow you to configure instance-wide settings that affect all organizations and users.

Language Settings

Get Supported Languages

Returns all languages supported by the ZITADEL system.

HTTP Request

GET /admin/v1/languages

Permissions

Requires authenticated user.

Response

languages · array

Array of supported language codes (e.g., [“en”, “de”, “fr”]).

Example Request

curl -X GET 'https://api.zitadel.cloud/admin/v1/languages' \
  -H 'Authorization: Bearer <TOKEN>'

Get Allowed Languages

Returns languages that are allowed in the instance. If languages are restricted, only those are returned. Otherwise, all supported languages are returned.

HTTP Request

GET /admin/v1/languages/allowed

Permissions

Requires authenticated user.

Get Default Language

Returns the default/fallback language used when a user’s preferred language is not available.

HTTP Request

GET /admin/v1/languages/default

Permissions

Requires iam.read permission.

Response

language · string

The default language code (e.g., “en”).

Set Default Language

Sets the default/fallback language for the instance.

HTTP Request

PUT /admin/v1/languages/default/{language}

Permissions

Requires iam.write permission.

Path Parameters

language · string · required

The language code to set as default (e.g., “en”, “de”).

Example Request

curl -X PUT 'https://api.zitadel.cloud/admin/v1/languages/default/en' \
  -H 'Authorization: Bearer <TOKEN>'

OIDC Settings

Get OIDC Settings

Returns the OIDC settings that define token lifetimes for the instance.

HTTP Request

GET /admin/v1/settings/oidc

Permissions

Requires iam.read permission.

Response

settings · object

OIDC configuration.

access_token_lifetime · string

Lifetime of access tokens (e.g., “12h”).

id_token_lifetime · string

Lifetime of ID tokens (e.g., “12h”).

refresh_token_idle_expiration · string

Idle timeout for refresh tokens (e.g., “720h”).

refresh_token_expiration · string

Absolute expiration for refresh tokens (e.g., “2160h”).

Example Request

curl -X GET 'https://api.zitadel.cloud/admin/v1/settings/oidc' \
  -H 'Authorization: Bearer <TOKEN>'

Add OIDC Settings

Creates new OIDC settings for the instance.

HTTP Request

POST /admin/v1/settings/oidc

Permissions

Requires iam.write permission.

Request Body

access_token_lifetime · string

Lifetime for access tokens (duration format, e.g., “12h”).

id_token_lifetime · string

Lifetime for ID tokens (duration format, e.g., “12h”).

refresh_token_idle_expiration · string

Idle timeout for refresh tokens (duration format, e.g., “720h”).

refresh_token_expiration · string

Absolute expiration for refresh tokens (duration format, e.g., “2160h”).

Update OIDC Settings

Updates existing OIDC settings for the instance.

HTTP Request

PUT /admin/v1/settings/oidc

Permissions

Requires iam.write permission.

Request Body

Same as Add OIDC Settings.

Example Request

curl -X PUT 'https://api.zitadel.cloud/admin/v1/settings/oidc' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token_lifetime": "12h",
    "id_token_lifetime": "12h",
    "refresh_token_idle_expiration": "720h",
    "refresh_token_expiration": "2160h"
  }'

Security Settings

Get Security Policy

Returns the security settings of the ZITADEL instance.

HTTP Request

GET /admin/v1/policies/security

Permissions

Requires iam.policy.read permission.

Response

policy · object

Security policy configuration.

enable_iframe_embedding · boolean

Whether iframe embedding is allowed.

allowed_origins · array

List of origins allowed for iframe embedding.

enable_impersonation · boolean

Whether user impersonation is enabled.

Example Request

curl -X GET 'https://api.zitadel.cloud/admin/v1/policies/security' \
  -H 'Authorization: Bearer <TOKEN>'

Set Security Policy

Updates the security settings of the ZITADEL instance.

HTTP Request

PUT /admin/v1/policies/security

Permissions

Requires iam.policy.write permission.

Request Body

enable_iframe_embedding · boolean

Allow the login UI to be embedded in iframes.

allowed_origins · array

List of origins allowed to embed the login UI (when iframe embedding is enabled).

enable_impersonation · boolean

Allow administrators to impersonate users.

Example Request

curl -X PUT 'https://api.zitadel.cloud/admin/v1/policies/security' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "enable_iframe_embedding": false,
    "allowed_origins": [],
    "enable_impersonation": true
  }'

Secret Generators

List Secret Generators

Lists all configured secret generators that define how secrets (verification codes, OTPs, etc.) are generated.

HTTP Request

POST /admin/v1/secretgenerators/_search

Permissions

Requires iam.read permission.

Get Secret Generator

Returns configuration for a specific secret generator type.

HTTP Request

GET /admin/v1/secretgenerators/{generator_type}

Permissions

Requires iam.read permission.

Path Parameters

generator_type · enum · required

Type of generator (e.g., “PasswordResetCode”, “EmailVerificationCode”).

Update Secret Generator

Updates configuration for a secret generator.

HTTP Request

PUT /admin/v1/secretgenerators/{generator_type}

Permissions

Requires iam.write permission.

Path Parameters

generator_type · enum · required

Type of generator to update.

Request Body

length · integer

Length of generated secrets.

expiry · string

How long the secret remains valid (duration format).

include_lower_letters · boolean

Include lowercase letters in the secret.

include_upper_letters · boolean

Include uppercase letters in the secret.

include_digits · boolean

Include digits in the secret.

include_symbols · boolean

Include symbols in the secret.

Notes

• These settings apply to all organizations in the instance
• Token lifetimes affect all OIDC applications
• Security policies should be carefully configured to balance security and usability
• Secret generator settings affect password reset codes, email verification, OTP, etc.