# Shared browser sessions

Status: activated for fresh Hybrid ID browser sign-ins on 2026-10-06 (provider/portal source `5f14d7a`, native source `1ca26db`). Each other application must adopt and verify this contract before extending its own local sessions. Existing sessions were not silently extended. Real owner-account acceptance is separate from the automated tests.

Hybrid ID owns the user's inactivity preference under **Security & sessions → Stay signed in**. Choices: 30 minutes, 1, 2, 4, 8 (default), 24, 36, or 168 hours. Foreground authenticated activity renews the shared inactivity deadline. Every browser sign-in ends at most 30 days after fresh authentication. Neither SSO reuse nor a preference change resets that limit. A revoked or expired session cannot be renewed.

## Application server contract

`POST https://auth.hybrid-id.com/sessions/browser` with `Content-Type: application/json` and HTTP Basic authentication using the registered confidential application's client ID and client secret. Use HTTPS with redirects disabled. Do not call from browser JavaScript or disclose the client secret, access token or session handle. The user's subject must be the pairwise `sub` your backend validated during OIDC sign-in, never an email or native Identity ID.

1. After Authorization Code + PKCE and full ID-token validation, enroll using the current 300-second OIDC access token:

```json
{"operation":"enroll","access_token":"<current OIDC access token>","subject":"<validated pairwise sub>"}
```

2. Keep the returned `session_handle` encrypted on your application server. Bind it to that exact browser session and subject. For protected use, validate current status:

```json
{"operation":"status","session_handle":"<server-held hbs_ handle>","subject":"<same pairwise sub>"}
```

3. On real authenticated foreground user activity, send the same object with `operation:"activity"`. This checks expiry before renewing. Do not send activity from timers, background tasks, hidden tabs, agent jobs, token refreshes or passive polling. A visible focused page's trusted user input can trigger a same-origin, CSRF-protected request to your backend, throttled to at most once per minute; server-side user operations can also report genuine activity. This is an integrator responsibility, not proof that an untrusted app is operated by a human.

4. Local application logout removes your cookie and server session and sends `operation:"revoke"` for the handle. It does not end other applications. Use the normal OIDC end-session flow when the user explicitly chooses shared Hybrid ID sign-out. Native session revocation, account disablement, approval withdrawal and application disablement override this policy.

An example status response (timestamps are illustrative Unix UTC seconds):

```json
{
  "schema":"hybrid.browser-session-policy.v1",
  "client_id":"example-client",
  "subject":"pairwise-subject",
  "active":true,
  "idle_timeout_seconds":28800,
  "hard_lifetime_seconds":2592000,
  "revision":2,
  "authenticated_at":1800000000,
  "last_activity_at":1800003600,
  "idle_expires_at":1800032400,
  "hard_expires_at":1802592000,
  "checked_at":1800003600,
  "valid_until":1800003660
}
```

Enrollment adds `session_handle`. Retrying enrollment with the same still-valid access token returns the same existing handle. Status and activity do not issue access tokens and confer no profile, company, Vault, wallet, workload, reviewer or sensitive-action authority. Existing API scopes, consent, billing and fresh security checks remain required. Use the normal OIDC authorization flow to obtain a new short-lived access token; valid shared authentication may allow silent SSO, but errors such as `login_required` must return the user to sign-in.

## Enforcement, clocks and outages

- Check current parent validity before allowing protected app access. A cached response is usable only until `valid_until`, never more than 60 seconds from `checked_at` and never past either deadline. Bind that cache to the same handle, client and subject. Use synchronized clocks and a conservative local expiry; clock uncertainty is not a reason to extend access.
- `401`: invalid/revoked/expired session, missing approval or invalid application credential. Stop protected access. Clear an expired user session and reconnect through normal OIDC; diagnose client authentication failures server-side.
- `400`/`413`: invalid or oversized input. Correct the integration; do not fall back to an unchecked local session.
- `503`, transport failure or malformed response: authority is unavailable. Once any previously validated interval ends, pause protected operations and show a reconnect/retry state. Do not report an outage as a successful renewal.
- The response is authenticated by HTTPS and confidential client authentication; it is not a signed offline credential. Do not infer ongoing validity from an old ID token or stored deadline.
- Increasing inactivity applies on the next still-valid activity. Shortening applies to existing families against their last activity and may end a session immediately. Existing pre-rollout sessions keep their previous deadline and need a fresh sign-in to adopt the new family.
- A successful shared logout removes provider access immediately and revokes native children. If native authority is unavailable, shared revocation stays in a durable retry queue and the operation must not be described as fully confirmed. No queue operation counts as activity.

## Native Hybrid ID boundaries

Hybrid ID's own portal uses its existing private native session bridge, with an immutable parent binding and current native introspection. Its cookies may persist until the original hard deadline, but every authenticated request is checked against current idle expiry and revocation. This does not grant native credentials to unrelated apps.

The OpenAPI schema is [browser-sessions.openapi.json](https://hybrid-id.com/integrations/browser-sessions.openapi.json). The main developer guide links this contract. Application adoption remains a separate deployment and acceptance step; this document alone is not evidence that Cortex, Chain, Federation or any other service has switched.

## Cortex scoped connections

Cortex adopts this policy with [session-bound scoped connections](./browser-connections.md). No independent one-hour connection lifetime is introduced.


## Application-only and shared sign-out choices

The provider sign-out page presents two explicit choices:

- **Only sign out of this application** ends the requesting client's provider
  authorization, preserves shared Hybrid ID sign-in and other applications, and
  returns to the client's registered post-logout destination. The application
  must still clear/revoke its own local session; Hybrid-Chain already does this
  before opening the provider page.
- **Also sign out of Hybrid ID** additionally ends the shared provider session
  and invokes existing native session-family revocation.

Both choices use a one-use CSRF-protected confirmation. The application-only
choice does not submit `logout`; the broader choice explicitly submits
`logout=yes`. Missing clients instead see **Keep me signed in**. No user-supplied
return URL is trusted. Do not interpret app logout as consent withdrawal or change
inactivity/hard-expiry policy. The remaining valid shared session can be reused
later through ordinary SSO without entering credentials again.

## Hybrid Verify adoption

Verify uses the same native inactivity and hard deadlines. It no longer limits
browser access to its one-hour OAuth bootstrap token. Sessions are encrypted in
an owner-only service state directory, outside releases, so deployments do not
remove them. Only foreground user interaction calls `activity`; status checks do
not extend inactivity. Native expiry/revocation still ends access; transient
checks pause access without deleting the session.

The registered verification portal may enroll `kind: "verification"` through
`/sessions/connections`, using a current token and the matching browser handle.
Its connection retains only the token's existing, currently consented scopes.
The server supplies that opaque connection in the existing verification bridge's
`access_token` field. Each use checks the native session, client, subject, grant,
consent and current owner. It grants no new evidence, reviewer, wallet or agent
rights. The connection remains server-only and is not an OAuth token for other
APIs. Local Verify sign-out revokes its browser handle and deletes its local
session; it does not sign the user out of Hybrid ID.

Existing sessions created by the old in-memory portal need one fresh SSO
connection to migrate. No password, MFA code, token or identity document should
be sent to an operator for this migration.
