Skip to content
Documentation
  • There are no suggestions because the search field is empty.

Configure OIDC Token Lifetimes in ZITADEL

How to set OIDC token lifetimes below UI minimums via Console (decimals), Admin API (seconds precision), or Terraform

Overview

ZITADEL lets you control the lifetimes of all OIDC tokens at the instance level: Access Token Lifetime, ID Token Lifetime, Refresh Token Expiration (absolute), and Refresh Token Idle Expiration (sliding/inactivity). These settings apply to all orgs/clients on the instance.

Goal: Configure values smaller than the default UI granularity (e.g., sub-day durations for the refresh tokens, or sub-hour durations for access/ID tokens).

You have three supported paths:

  1. Console (UI): use decimal values in the fields that are expressed in days to achieve sub-day durations (e.g., 0.5 days = 12 hours).

  2. Admin API: send duration strings with seconds (e.g., 3600s, 43200s, 30s).

  3. Terraform: declare durations as strings on the zitadel_default_oidc_settings resource.

What each setting means (quick refresher)

  • Access Token Lifetime — validity of access tokens (JWT or opaque).

  • ID Token Lifetime — validity of ID tokens.

  • Refresh Token Expiration (absolute) — hard end of life regardless of activity.

  • Refresh Token Idle Expiration (sliding) — max inactivity window before the refresh token becomes invalid.

Option A — Console (UI) using decimals

  1. Go to Default Settings → OIDC token lifetimes and expiration.

  2. For fields shown in days (Refresh Token Expiration / Idle Expiration), enter a decimal to reach sub-day values:

    • 0.5 day → 12 hours

    • 0.125 day → 3 hours

  3. Save the changes.

This lets you go below whole-day values directly in the UI. 

Option B — Admin API (seconds-level precision)

The Admin API lets you update OIDC settings with duration strings in s (e.g., 12 hours would be 43200s).

Endpoint: PUT /admin/v1/settings/oidc (Update existing OIDC settings for the instance).

Example:

curl -X PUT "https://<your-domain>/admin/v1/settings/oidc" \

  -H "Authorization: Bearer <admin_access_token>" \

  -H "Content-Type: application/json" \

  -d '{

    "accessTokenLifetime": "3600s",

    "idTokenLifetime": "43200s",

    "refreshTokenIdleExpiration": "604800s",

    "refreshTokenExpiration": "2592000s"

}'

Note: You need to send all four OIDC settings in the request, even when updating just one.

Verify your changes by reading them back: GET /admin/v1/settings/oidc.

Option C — Terraform (declarative & repeatable)

Use the official provider’s zitadel_default_oidc_settings resource to declare durations as strings and manage them via IaC.

# Example: sub-hour / sub-day durations

resource "zitadel_default_oidc_settings" "oidc" {

  access_token_lifetime         = "45m0s"

  id_token_lifetime             = "45m0s"

  refresh_token_idle_expiration = "12h0m0s"  # sliding inactivity window

  refresh_token_expiration      = "36h0m0s"  # absolute max lifetime

}

See the provider docs link below for the full attribute list and latest schema.

Related references