Session Configuration

Session Configuration controls how authenticated sessions in the Monte Carlo web application behave. Today this surface exposes two timeout settings per Monte Carlo account — an absolute session lifetime (max age) and an inactivity timeout — and may grow to cover other session-related controls in the future. When either timer is exceeded, the user's session is rejected on the next request and they are required to re-authenticate. The configuration is managed via the GraphQL API using two operations: get and update.

👍

Session Configuration applies to the Monte Carlo web application only. It does not affect API tokens, agent connections, or integration endpoints — those are governed by their own credentials and, where applicable, by Network Access Control.

Timeout settings

Each Monte Carlo account has two configurable timers. The defaults preserve Monte Carlo's pre-existing behavior, so accounts that never call updateSessionSettings see no change.

👍

When the inactivity timeout is enabled, it must be less than or equal to maxAgeMinutes. Configuring an inactivity window longer than the absolute session lifetime is rejected by validation, since the absolute timer would always fire first.

Behavior

• Absolute lifetime is anchored to the original authentication. The maxAgeMinutes clock starts when the user authenticates with the identity provider. Once the configured maximum is reached, the session is rejected and the browser must go back through the login flow (see below) to obtain a new session.
• Inactivity is measured server-side. The session's last-activity timestamp is updated on requests that reach Monte Carlo's auth layer. Background requests that the browser issues automatically (such as polling) refresh activity, just as user-initiated requests do.
• Either timer fires independently. A session is rejected when either the absolute lifetime is exhausted or (when enabled) the inactivity window has elapsed since the last recorded activity.
• Once a session is rejected, the user is redirected to the login page. If the identity provider still has a valid session, sign-in completes silently; otherwise, the user needs to re-enter credentials.

Permissions

Reading and updating these settings requires the following permissions:

Account Owners receive both permissions automatically. Other roles can be granted these permissions through Monte Carlo's authorization model in the same way other settings permissions are granted.

Usage

👍

How Can I Use the API?

You can access the API through the API Explorer in the Monte Carlo UI. Learn more about the API Explorer here.

Alternatively, you can generate an API key and make API calls using tools such as cURL or Postman.

Reading current settings

Use the getSessionSettings query to retrieve the current session timeout configuration for the calling user's account.

query GetSessionSettings {
  getSessionSettings {
    inactivityTimeoutMinutes
    maxAgeMinutes
  }
}

{
  "data": {
    "getSessionSettings": {
      "inactivityTimeoutMinutes": 0,
      "maxAgeMinutes": 2880
    }
  }
}

Updating settings

Use the updateSessionSettings mutation to set new values. Both arguments are required and replace the current configuration.

mutation UpdateSessionSettings {
  updateSessionSettings(
    inactivityTimeoutMinutes: 30
    maxAgeMinutes: 480
  ) {
    sessionSettings {
      inactivityTimeoutMinutes
      maxAgeMinutes
    }
  }
}

{
  "data": {
    "updateSessionSettings": {
      "sessionSettings": {
        "inactivityTimeoutMinutes": 30,
        "maxAgeMinutes": 480
      }
    }
  }
}

Parameters:

• inactivityTimeoutMinutes (required) — 0 to disable inactivity-based expiry, or an integer in [30, 1440]. When enabled, must not exceed maxAgeMinutes.
• maxAgeMinutes (required) — Integer in [30, 10080].

If either argument is outside its allowed range, or if inactivityTimeoutMinutes exceeds maxAgeMinutes while enabled, the mutation returns a GraphQL error and no change is persisted.

Examples

Enable an 8-hour session with a 30-minute inactivity timeout

A common configuration: users must re-authenticate at least once every 8 hours, and any session left idle for 30 minutes is invalidated.

mutation UpdateSessionSettings {
  updateSessionSettings(
    inactivityTimeoutMinutes: 30
    maxAgeMinutes: 480
  ) {
    sessionSettings {
      inactivityTimeoutMinutes
      maxAgeMinutes
    }
  }
}

Shorten the absolute session lifetime without enabling inactivity expiry

To require daily re-authentication while leaving idle behavior unchanged:

mutation UpdateSessionSettings {
  updateSessionSettings(
    inactivityTimeoutMinutes: 0
    maxAgeMinutes: 1440
  ) {
    sessionSettings {
      inactivityTimeoutMinutes
      maxAgeMinutes
    }
  }
}

Restore defaults

To revert to Monte Carlo's default behavior (48-hour absolute lifetime, no inactivity expiry):

mutation UpdateSessionSettings {
  updateSessionSettings(
    inactivityTimeoutMinutes: 0
    maxAgeMinutes: 2880
  ) {
    sessionSettings {
      inactivityTimeoutMinutes
      maxAgeMinutes
    }
  }
}

FAQs

Is session configuration on a per–Monte Carlo account (workspace) basis?

Yes. Settings are applied per Monte Carlo account (workspace). If you have multiple accounts, you can configure each one independently.

When do new settings take effect?

Updates apply to new sessions issued after the change. Existing sessions continue to use the timers that were in effect when they were issued; they are not retroactively shortened. Users with existing sessions will pick up the new settings the next time they sign in.

Can a user stay signed in past maxAgeMinutes by remaining active?

No. The absolute lifetime is independent of activity. Once maxAgeMinutes has elapsed since the user's original authentication, the next request fails authentication and the user is sent to the login page — even if they have been continuously active.

Will reducing the timeouts log out current users immediately?

No. Active sessions retain the timers they were issued with, and they expire on their original schedule. Tightening the configuration does not produce a forced-logout wave.

Do these settings affect API tokens or integrations?

No. These settings govern only interactive web-application sessions. API tokens, agent connections, and integration endpoints are not affected and continue to be controlled by their own credentials and, where applicable, by Network Access Control.

What happens when a session is rejected?

The user is redirected to the Monte Carlo login page. If their identity provider still has an active session, sign-in completes silently and the user is returned to where they were. Otherwise, they need to re-enter credentials.

API Documentation

Detailed documentation for these operations is available in our API documentation:

• getSessionSettings
• updateSessionSettings