> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `claude plugin marketplace add scalekit-inc/claude-code-authstack && claude plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Organization session policy

Override application-level session timeouts for specific organizations with custom absolute and idle session policies
By default, all organizations inherit the session policy configured at the application level — covering absolute session duration and idle timeout. When an enterprise customer requires stricter or different session controls than your application defaults, you can set a custom session policy on a per-organization basis.

Scalekit always enforces the **stricter of the two** (application vs. organization) at session creation time, so organization policies can only tighten — not relax — your application-level defaults.

## How it works

Each organization can either inherit the application session policy or define its own. The two settings you can customize per organization are:

| Setting | Behavior |
|---|---|
| **Absolute session timeout** | Maximum session lifetime regardless of activity. Scalekit applies `min(app value, org value)`. |
| **Idle session timeout** | Inactivity period after which the session expires. Enabled if either the app or org has it on; duration is `min(app value, org value)`. |

**Access token lifetime** is not configurable at the org level. It remains an application-level setting only.

> note: Validation rules
>
> Custom policy values must satisfy this chain:
>
> ```
> org absolute session timeout > org idle session timeout > app access token expiry
> ```

## Set up custom session policy for an organization

### Prerequisites

Enable the **Session Policy** feature for an organization before configuring a custom policy. Navigate to **Dashboard > Organizations > [Organization] > Overview > Edit** and turn on **Session Policy** feature. You can also use the [organization settings API](/apis/#tag/organizations/PATCH/api/v1/organizations/{id}/settings).

> Image: Enable session policy feature for organization.

### Configure via dashboard

Once the **Session Policy** feature is enabled for the organization, you can configure a custom policy for the organization via the Scalekit dashboard.

1. Go to **Dashboard > Organizations** and open the organization.
2. Click the **Session Policy** tab.
3. Select **Custom** to apply org-specific settings, or **Application** to revert to defaults.
4. Set the **Absolute session timeout** and **Idle session timeout** for the organization.
5. Click **Save**.

> Image: Edit session policy for the organization.

### Let org admins self-serve via Hosted Widgets

You can let your customers manage their own session policy through [Hosted Widgets](/authenticate/manage-users-orgs/hosted-widgets/) — an embeddable self-service portal that lets your customers manage organization and user-level settings. When the `Session Policy` feature is enabled for an organization, the Session Policy widget becomes available in the Hosted Widget portal.

### Configure via API/SDK

1. **Get the current session policy**

   Retrieve the active session policy for an organization to display it in your settings UI or audit the current configuration.

   
     ### Node.js

```javascript title="Get session policy"
try {
  const policy = await scalekit.organization.getOrganizationSessionPolicy('org_12345');

  // policySource: 1 = APPLICATION (inheriting defaults), 2 = CUSTOM (org-specific values active)
  console.log('Policy source:', policy.policySource);
  console.log('Absolute timeout (minutes):', policy.absoluteSessionTimeout);
  console.log('Idle timeout enabled:', policy.idleSessionTimeoutEnabled);
} catch (error) {
  console.error('Failed to get session policy:', error.message);
}
```

     ### Python

```python title="Get session policy"
from scalekit.v1.organizations.organizations_pb2 import SessionPolicyType

try:
    response, _ = scalekit_client.organization.get_organization_session_policy('org_12345')
    policy = response.policy

    if policy.policy_source == SessionPolicyType.CUSTOM:
        print('Absolute timeout (minutes):', policy.absolute_session_timeout.value)
        print('Idle timeout enabled:', policy.idle_session_timeout_enabled.value)
except Exception as e:
    print('Failed to get session policy:', e)
```

     ### Go

```go title="Get session policy"
policy, err := scalekitClient.Organization().GetOrganizationSessionPolicy(ctx, "org_12345")
if err != nil {
    log.Fatal(err)
}

if policy.PolicySource == scalekit.SessionPolicySourceCustom {
    fmt.Println("Absolute timeout (minutes):", policy.AbsoluteSessionTimeout.GetValue())
    fmt.Println("Idle timeout enabled:", policy.IdleSessionTimeoutEnabled.GetValue())
}
```

     ### Java

```java title="Get session policy"
import com.scalekit.grpc.scalekit.v1.organizations.OrganizationSessionPolicySettings;
import com.scalekit.grpc.scalekit.v1.organizations.SessionPolicyType;

try {
    OrganizationSessionPolicySettings policy =
        scalekitClient.organizations().getOrganizationSessionPolicy("org_12345");

    if (policy.getPolicySource() == SessionPolicyType.CUSTOM) {
        System.out.println("Absolute timeout (minutes): " + policy.getAbsoluteSessionTimeout().getValue());
        System.out.println("Idle timeout enabled: " + policy.getIdleSessionTimeoutEnabled().getValue());
    }
} catch (Exception e) {
    System.err.println("Failed to get session policy: " + e.getMessage());
}
```

   

2. **Set a custom session policy**

   Apply a custom policy when an organization requires different session durations than your application defaults.

   
     ### Node.js

```javascript title="Set custom session policy"
try {
  const updated = await scalekit.organization.updateOrganizationSessionPolicy('org_12345', {
    policySource: 'CUSTOM',
    absoluteSessionTimeout: 480,
    absoluteSessionTimeoutUnit: 'MINUTES',
    idleSessionTimeoutEnabled: true,
    idleSessionTimeout: 60,
    idleSessionTimeoutUnit: 'MINUTES',
  });

  console.log('Policy updated:', updated.policySource);
} catch (error) {
  console.error('Failed to update session policy:', error.message);
}
```

     ### Python

```python title="Set custom session policy"
from scalekit.v1.organizations.organizations_pb2 import SessionPolicyType
from scalekit.v1.commons.commons_pb2 import TimeUnit

try:
    response, _ = scalekit_client.organization.update_organization_session_policy(
        organization_id='org_12345',
        policy_source=SessionPolicyType.CUSTOM,
        absolute_session_timeout=480,
        absolute_session_timeout_unit=TimeUnit.MINUTES,
        idle_session_timeout_enabled=True,
        idle_session_timeout=60,
        idle_session_timeout_unit=TimeUnit.MINUTES,
    )

    print('Policy updated:', response.policy.policy_source)
except Exception as e:
    print('Failed to update session policy:', e)
```

     ### Go

```go title="Set custom session policy"
timeout := int32(480)
idleTimeout := int32(60)
idleEnabled := true

updated, err := scalekitClient.Organization().UpdateOrganizationSessionPolicy(ctx, "org_12345", scalekit.OrganizationSessionPolicy{
    PolicySource:               scalekit.SessionPolicySourceCustom,
    AbsoluteSessionTimeout:     &timeout,
    AbsoluteSessionTimeoutUnit: scalekit.TimeUnitMinutes,
    IdleSessionTimeoutEnabled:  &idleEnabled,
    IdleSessionTimeout:         &idleTimeout,
    IdleSessionTimeoutUnit:     scalekit.TimeUnitMinutes,
})
if err != nil {
    log.Fatal(err)
}

fmt.Println("Policy updated:", updated.PolicySource)
```

     ### Java

```java title="Set custom session policy"
import com.google.protobuf.Int32Value;
import com.google.protobuf.BoolValue;
import com.scalekit.grpc.scalekit.v1.commons.TimeUnit;
import com.scalekit.grpc.scalekit.v1.organizations.OrganizationSessionPolicySettings;
import com.scalekit.grpc.scalekit.v1.organizations.SessionPolicyType;

try {
    OrganizationSessionPolicySettings policy = OrganizationSessionPolicySettings.newBuilder()
        .setPolicySource(SessionPolicyType.CUSTOM)
        .setAbsoluteSessionTimeout(Int32Value.of(480))
        .setAbsoluteSessionTimeoutUnit(TimeUnit.MINUTES)
        .setIdleSessionTimeoutEnabled(BoolValue.of(true))
        .setIdleSessionTimeout(Int32Value.of(60))
        .setIdleSessionTimeoutUnit(TimeUnit.MINUTES)
        .build();

    OrganizationSessionPolicySettings updated =
        scalekitClient.organizations().updateOrganizationSessionPolicy("org_12345", policy);

    System.out.println("Policy updated: " + updated.getPolicySource());
} catch (Exception e) {
    System.err.println("Failed to update session policy: " + e.getMessage());
}
```

   

3. **Revert to application defaults**

   Remove the custom policy and restore the organization to the application-level session settings.

   
     ### Node.js

```javascript title="Revert to application defaults"
try {
  await scalekit.organization.updateOrganizationSessionPolicy('org_12345', {
    policySource: 'APPLICATION',
  });
} catch (error) {
  console.error('Failed to revert session policy:', error.message);
}
```

     ### Python

```python title="Revert to application defaults"
from scalekit.v1.organizations.organizations_pb2 import SessionPolicyType

try:
    scalekit_client.organization.update_organization_session_policy(
        organization_id='org_12345',
        policy_source=SessionPolicyType.APPLICATION,
    )
except Exception as e:
    print('Failed to revert session policy:', e)
```

     ### Go

```go title="Revert to application defaults"
_, err := scalekitClient.Organization().UpdateOrganizationSessionPolicy(ctx, "org_12345", scalekit.OrganizationSessionPolicy{
    PolicySource: scalekit.SessionPolicySourceApplication,
})
if err != nil {
    log.Fatal(err)
}
```

     ### Java

```java title="Revert to application defaults"
import com.scalekit.grpc.scalekit.v1.organizations.OrganizationSessionPolicySettings;
import com.scalekit.grpc.scalekit.v1.organizations.SessionPolicyType;

try {
    OrganizationSessionPolicySettings policy = OrganizationSessionPolicySettings.newBuilder()
        .setPolicySource(SessionPolicyType.APPLICATION)
        .build();

    scalekitClient.organizations().updateOrganizationSessionPolicy("org_12345", policy);
} catch (Exception e) {
    System.err.println("Failed to revert session policy: " + e.getMessage());
}
```


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |