Skip to main content

User Token Expiration Configuration REST API

The user token expiration configuration API allows System Administrators to manage the expiration period for user tokens. This configuration determines how long user tokens remain valid and is enforced during authentication.

Base Path: /api/v2/config/userTokens

Access to all endpoints requires the System Administrator role.

Expiration Behavior

When an expiration configuration is set, IQ Server validates the age of each user token during authentication:

  • If the token is within the configured limit, authentication succeeds.

  • If the token exceeds the configured limit, IQ Server returns HTTP 401 Unauthorized with the message: “User token has expired. Please generate a new token.”

Expiration is based on the creation time of the token and applies to both existing and new tokens. Changes to the configuration (including enabling, updating, or resetting) take effect immediately and are evaluated on the next authentication attempt.

Get User Token Configuration

HTTP Method: GET

Endpoint: /api/v2/config/userTokens

Retrieves the current user token expiration configuration.

Success Response:

Status Code: 200 OK

Response Body:

{
  "userTokenDefaultExpirationDays": 30
}

Field:

  • userTokenDefaultExpirationDays (Integer) – Number of days before user tokens expire.

    Returns null when expiration is disabled.

Example cURL:

curl -u admin:admin123 -X GET http://localhost:8070/api/v2/config/userTokens

Update User Token Configuration

HTTP Method: PUT

Endpoint: /api/v2/config/userTokens

Updates the user token expiration configuration. Only provided fields are updated. null values are ignored.

Request Body:

{
  "userTokenDefaultExpirationDays": <days>
}

Request Fields:

  • userTokenDefaultExpirationDays (Integer, optional, 1–365) – Number of days before user tokens expire. null values are ignored.

Success Response:

Status Code: 200 OK

Returns the updated configuration.

Example cURL:

curl -u admin:admin123 -X PUT -H "Content-Type: application/json" \
    -d '{"userTokenDefaultExpirationDays": 90}' \
    http://localhost:8070/api/v2/config/userTokens

Example Response:

{
  "userTokenDefaultExpirationDays": 90
}

Reset User Token Configuration

HTTP Method: DELETE

Endpoint: /api/v2/config/userTokens?property=<property-name>

Resets specified user token configuration properties to their default values.

Query Parameters:

  • property (String, required) – Name of the property to reset. Valid value: userTokenDefaultExpirationDays

Success Response:

Status Code: 200 OK

Returns the configuration after reset.

Example cURL:

curl -u admin:admin123 -X DELETE \
  "http://localhost:8070/api/v2/config/userTokens?property=userTokenDefaultExpirationDays"

Example Response:

{
  "userTokenDefaultExpirationDays": null
}