Authentication

Every Local API request requires a bearer token.

Request format

curl \
  -H "Authorization: Bearer $SESSIONDOCK_TOKEN" \
  "$SESSIONDOCK_BASE_URL/health"

If the token is missing or wrong, the API responds with 401 unauthorized.

Modes

SessionDock exposes three modes:

• disabled
• read-only
• full-automation

Read-only mode

Safe for:

• health checks
• session search and browsing
• tag counts
• preview inspection
• waveform reads

Full-automation mode

Required for:

• session creation
• session patch and delete
• notes and tags replacement
• waveform notes updates
• import jobs
• open and focus actions

Configured mode versus effective mode

The health endpoint reports both values because the desktop app can downgrade writes in practice.

• configured mode is what the user selected in preferences
• effective mode is what SessionDock actually allows at runtime

This matters when a workflow requests full automation but the app is unable to grant writes in the current license or runtime context.

Design recommendation

Treat effectiveMode as the source of truth in clients. A launcher or assistant should not assume writes are available just because the configured mode says so.

Authentication failures to handle

• missing token
• stale token after user regeneration
• write attempted while running in read-only effective mode

Practical client behavior

1. Call /health once at startup.
2. Cache effectiveMode for UI gating.
3. Surface write failures as actionable messages rather than generic network errors.