Client Flow Map

Client Flow Map

Purpose: define the expected top-level sequence for clients integrating with jsonlog.

Primary Flows

1. Bootstrap auth against auth.jsonlog.com and acquire a Bearer token for account-scoped routes.
2. Send logs over POST /log (public or channel-specific) with a JSON body.
3. Stream real-time logs over GET /ws upgrade with optional cid and level filters.
4. Enforce private channel access by account claim (acc) for HTTP and WebSocket reads/writes.
5. Discover durable SSTable files via POST /query and inspect aggregates via GET /query/stats.
6. Monitor service readiness and write-path state via GET /health and GET /stats.

Endpoint Families

• Ingestion:
  • POST /log
  • GET /log
• Streaming:
  • GET /ws (WebSocket upgrade endpoint)
• Query:
  • POST /query
  • GET /query/stats
• Service:
  • GET /health
  • GET /stats
• Docs:
  • GET /openapi.json
  • GET /docs
  • GET /swagger

Security Expectations

• JWT signature verification uses https://auth.jsonlog.com/.well-known/jwks.json?client_id=cid_jsonlog by default.
• /query routes require Bearer auth and use JWT acc for account isolation.
• Private channel access requires JWT acc to match the channel owner account.
• Unauthorized private-channel reads return 404 to avoid channel discovery.
• No-auth usage is local-development only and should not be the production default.