galaxy-game/authsession/docs/examples.md

Configuration And Contract Examples

The examples below are illustrative. Values such as keys, codes, and IDs are placeholders unless explicitly stated otherwise.

Example Environment

Minimal local-development shape:

AUTHSESSION_REDIS_ADDR=127.0.0.1:6379
AUTHSESSION_PUBLIC_HTTP_ADDR=:8080
AUTHSESSION_INTERNAL_HTTP_ADDR=:8081

AUTHSESSION_USER_SERVICE_MODE=stub
AUTHSESSION_MAIL_SERVICE_MODE=stub

OTEL_SERVICE_NAME=galaxy-authsession
OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=none

Example REST-backed integration shape:

AUTHSESSION_REDIS_ADDR=127.0.0.1:6379

AUTHSESSION_USER_SERVICE_MODE=rest
AUTHSESSION_USER_SERVICE_BASE_URL=http://127.0.0.1:8091
AUTHSESSION_USER_SERVICE_REQUEST_TIMEOUT=1s

AUTHSESSION_MAIL_SERVICE_MODE=rest
AUTHSESSION_MAIL_SERVICE_BASE_URL=http://127.0.0.1:8092
AUTHSESSION_MAIL_SERVICE_REQUEST_TIMEOUT=1s

Public Auth HTTP Examples

Start an e-mail challenge:

curl -X POST http://127.0.0.1:8080/api/v1/public/auth/send-email-code \
  -H 'Content-Type: application/json' \
  -d '{"email":"pilot@example.com"}'

Example response:

{
  "challenge_id": "challenge-123"
}

Confirm the challenge and register the device public key:

curl -X POST http://127.0.0.1:8080/api/v1/public/auth/confirm-email-code \
  -H 'Content-Type: application/json' \
  -d '{
    "challenge_id": "challenge-123",
    "code": "123456",
    "client_public_key": "11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no="
  }'

Example response:

{
  "device_session_id": "device-session-123"
}

Stable public error example:

{
  "error": {
    "code": "challenge_expired",
    "message": "challenge expired"
  }
}

Trusted Internal HTTP Examples

Read one session:

curl http://127.0.0.1:8081/api/v1/internal/sessions/device-session-123

Example response:

{
  "session": {
    "device_session_id": "device-session-123",
    "user_id": "user-123",
    "client_public_key": "11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no=",
    "status": "active",
    "created_at": "2026-04-05T12:00:00Z"
  }
}

Revoke one session:

curl -X POST http://127.0.0.1:8081/api/v1/internal/sessions/device-session-123/revoke \
  -H 'Content-Type: application/json' \
  -d '{"reason_code":"admin_revoke","actor":{"type":"system"}}'

Example response:

{
  "outcome": "revoked",
  "device_session_id": "device-session-123",
  "affected_session_count": 1
}

Block by e-mail:

curl -X POST http://127.0.0.1:8081/api/v1/internal/user-blocks \
  -H 'Content-Type: application/json' \
  -d '{"email":"pilot@example.com","reason_code":"policy_blocked","actor":{"type":"admin","id":"admin-1"}}'

Example response:

{
  "outcome": "blocked",
  "subject_kind": "email",
  "subject_value": "pilot@example.com",
  "affected_session_count": 0,
  "affected_device_session_ids": []
}

Redis Projection Examples

Gateway Session Cache Record

Example Redis key and JSON value written by authsession for gateway:

gateway:session:device-session-123

{
  "device_session_id": "device-session-123",
  "user_id": "user-123",
  "client_public_key": "11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no=",
  "status": "active"
}

Gateway Session-Event Stream Entry

Active snapshot:

redis-cli XADD gateway:session_events '*' \
  device_session_id device-session-123 \
  user_id user-123 \
  client_public_key 11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no= \
  status active

Revoked snapshot:

redis-cli XADD gateway:session_events '*' \
  device_session_id device-session-123 \
  user_id user-123 \
  client_public_key 11qYAYdk8v3K6Yw8QK6ZlQ2nP4Wm8Cq5g1H0K8vT9no= \
  status revoked \
  revoked_at_ms 1775121700000

Notes:

• projected field values are strings in the Redis Stream payload
• revoked_at_ms is written only for revoked snapshots
• duplicate full-snapshot stream events are acceptable
• the cache snapshot and stream event intentionally omit revoke reason and actor metadata because gateway does not consume them