> This page is for version V3 - Beta (default).
> For other versions, use one of these documentation indexes:
> - V3 - Beta (default): https://docs.authlyx.dev/v3/llms.txt
> - V2 - Legacy: https://docs.authlyx.dev/v2/llms.txt
> - V1 - End of support: https://docs.authlyx.dev/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.authlyx.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.authlyx.dev/_mcp/server.

# Sessions and heartbeats

> Sessions and heartbeats in AuthlyX, with examples and troubleshooting.

## A license login, from opening the app to signing out

Consider a customer opening MyApp on Windows. The app starts with its AppKey and version. Initialization returns application information and update settings. It does not authenticate the customer and does not grant access to protected app data.

The customer enters a license. Before submitting it, the SDK obtains a challenge using the installation's public key. It signs the challenge with the private key kept on that installation. AuthlyX checks the license, application rules, expiry and device limits before issuing an authenticated session.

```mermaid
flowchart TD
    A[Customer opens MyApp] --> B[Initialize using AppKey and app version]
    B --> C[Receive app settings and release information]
    C --> D[Customer chooses an enabled sign-in method]
    D --> L[License: submit the customer's key]
    D --> U[Username: submit username and password]
    D --> V[Device: submit the configured whitelisted identifier]
    L --> P[SDK obtains a challenge and signs installation proof]
    U --> P
    V --> P
    P --> Q{Does the identity pass access and app-policy checks?}
    Q -->|No| X[Return a rejection; do not issue an authenticated session]
    Q -->|Yes| S[Create server session tied to app, identity and installation]
    S --> T[Return token, session ID, identity data and access deadline]
    T --> R[MyApp requests a variable, script, feature or other protected data]
    R --> SIGN[SDK attaches token and signs the exact request]
    SIGN --> CHECK[Server validates session, proof and current access rules]
    CHECK --> DATA[Return requested data when allowed]
    T --> H[Heartbeat runs at the configured interval]
    H --> VALID{Session still valid?}
    VALID -->|Yes| EXT[Return renewed access deadline]
    EXT --> H
    VALID -->|Revoked or expired| LOCK[Stop protected actions and show the reason]
    VALID -->|Network failure| OFF[Consider existing valid offline permission]
    T --> OUT[Customer signs out]
    OUT --> END[Revoke online session and clear local access]
```

## What the session contains

The server associates the session with the application, authenticated user/license/device, installation public key, device identifier, app version and expiry. A session ID identifies that record. The bearer token authorizes protected requests together with the installation proof; a session ID alone is not a replacement for these credentials.

The SDK stores the active session in its client instance. It adds the token and request proof when you read cloud variables, fetch scripts, read public metadata, send logs or use other protected endpoints. Direct HTTP clients must send the same documented authentication and signing fields themselves.

## Why check again after login?

A customer can sign in at 9:00 and have their license paused at 9:05. Keeping the original login result forever would miss that change. A session check asks the server whether the linked identity, application and device are still allowed.

Use server heartbeat mode for automatic checks, or manual mode when your application schedules them. The server provides the interval; the configured fallback is ten minutes. An interval and an access deadline are different: permission is bounded by the deadline, not by a promise that the next network request will succeed.

## When access ends

For a definitive ban, pause, expiry or ended session, stop protected actions and show a clear message. Keep unsaved work available where possible. The SDK must not terminate the process or choose a new screen for you. Your application decides whether to return to login or show a locked screen.

A timeout does not prove a ban. Handle connection failures separately and use offline access only when a valid permit allows it. After sleep or resume, recheck the session before resuming protected work. Logout ends the online session and clears local access state.

## Test it

Sign in with a test license, check the session, then end it in the dashboard. Check again from the same running app. The old token must be rejected. Repeat with a paused license and with a network outage; those cases should produce different decisions.

See the SDK Check session page for language-specific calls and the Client API Sessions reference for direct requests.