aim-ws-token-management

Manage JWT access-token lifecycles to resolve WebSocket disconnect failures.

4|Updated May 17, 2026
One-click install
npx skills add https://github.com/hellopoisonx/aim --skill aim-ws-token-management
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: aim-ws-token-management
Source: https://github.com/hellopoisonx/aim/tree/main/skills/aim-ws-token-management
Command: npx skills add https://github.com/hellopoisonx/aim --skill aim-ws-token-management

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you prevent and resolve WebSocket mass disconnects caused by expired access tokens, misapplied JWT TTL configuration, and clients reconnecting with stale credentials.

Core Features & Use Cases

  • Diagnose WS token expiry disconnect storms: Identify whether the gateway is proactively closing connections with a token-expired status and correlate it with load-test timelines.
  • Verify and correct JWT TTL wiring: Trace TTL configuration from YAML through the JWTIssuer into the shared JWT manager, ensuring the configured AccessTTL is actually used when generating tokens.
  • Fix WSClient reconnect behavior with automatic token renewal: Ensure reconnect attempts refresh tokens via REST before reopening WS connections, preventing repeated 401 upgrade failures.
  • Ensure load-test token pipeline supplies refresh metadata: Confirm benchmark scenarios populate refresh_token, expires_at, and device_id so the refresh flow can succeed.

Quick Start

Ask the AI to explain why WS connections drop at ~5 minutes during your load test, then give a step-by-step checklist to confirm TTL config flow and validate WSClient auto-refresh is using the same token manager instance.

Frequently Asked Questions about aim-ws-token-management

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why do WebSocket connections drop at regular intervals during load testing?

WebSocket connections drop at regular intervals when JWT access tokens expire and the gateway proactively closes sessions with a token-expired status. This disconnect storm correlates with load-test timelines and repeated 401 upgrade failures from stale reconnect credentials.

How do I trace JWT TTL configuration to ensure it applies when generating tokens?

Trace JWT TTL configuration by following the wiring from your YAML configuration files through the JWTIssuer directly into the shared JWT manager. This verifies that the configured AccessTTL value is actually used during token issuance, preventing mismatched expiry timers that cause premature WebSocket disconnects.

How to fix WebSocket client reconnect behavior after token expiration?

Fix WebSocket client reconnect behavior by implementing automatic token renewal via REST before reopening WS connections. This prevents repeated 401 upgrade failures by ensuring the WSClient refreshes stale tokens using the same token manager instance before attempting any reconnection.

What token pipeline metadata is required for WebSocket load testing refresh flows?

Token pipeline metadata required for WebSocket load testing refresh flows includes refresh_token, expires_at, and device_id. Confirming benchmark scenarios populate these fields ensures the token refresh flow can succeed and prevents mass disconnects during load test execution.

Can I use this approach for production incident debugging or is it only for load testing?

You can use this approach for both production incident debugging and load testing scenarios. It resolves WebSocket mass disconnects by managing JWT lifecycles across gateway expiry timers and client reconnect flows, applying equally to live production outages and simulated benchmark environments.