- Standardize Python SDK (`datastack`) documentation with a new multi-file suite. - Update `datastack-sdk` to serve as a backward-compatible shim for the canonical `datastack` package. - Update project manifest and memory map to reflect current SDK structure and v2.2.0 features.
3.0 KiB
3.0 KiB
Client SDK Registry & Management (/vcon/clients)
DataStack enforces strict authentication for all telemetry sources. The Client Management workspace (/vcon/clients) allows operators to register client applications, generate and rotate JWT credentials, adjust per-client rate limits, and revoke access instantly.
1. Registering an SDK Client
To onboard a new application or telemetry producer:
- Navigate to Clients (
/vcon/clients) and click + Register Client. - Complete the form:
- Client Identifier (
clientId): A unique lowercase slug (e.g.,pos_terminal_01,mobile_app_prod,fleet_vehicle_42). Allowed characters:a-z,0-9,_,-. - Client Name: Human-readable label (e.g.,
Point of Sale Terminal #1). - Rate Limit (Events/sec): Maximum allowed throughput for this specific client (default:
100).
- Client Identifier (
- Click Register Client.
- Copy the Generated Token:
- DataStack generates a cryptographically random 32-character client secret.
- Using
DATASTACK_JWT_SECRET, DataStack signs an HMAC-SHA256 JWT payload containing:{ "clientId": "pos_terminal_01", "name": "Point of Sale Terminal #1", "rateLimit": 100, "iat": 1700000000 } - Store this token in your client's environment or configuration.
2. Managing Client Credentials & Lifecycle
Rotating Client Tokens
If a client secret or JWT token is compromised or needs routine rotation:
- Locate the client in the table and click Rotate Token.
- Confirm the prompt.
- DataStack generates a fresh client secret, signs a new JWT, and updates PostgreSQL.
- Instant Disconnection: Port 3000 calls
POST /internal/client-sync. The Port 4000 ingestion server immediately severs all active WebSocket connections holding the old token. The client must reconnect using the newly generated token.
Revoking Access
To temporarily pause ingestion from a specific client without deleting its history:
- Click the status dropdown or action button and select Revoke.
- The client status changes to
revoked. - Port 4000 immediately rejects new handshakes and terminates existing connections with
CLIENT_REVOKED (403). - HTTP requests to
POST /api/eventswith this token are rejected with403 Forbidden.
Restoring Access
- Select a revoked client and click Activate.
- Handshakes and HTTP ingestion are instantly permitted again.
Deleting a Client
When an application is permanently decommissioned:
- Click Delete Client.
- Choose whether to:
- Keep Historical Data: Retains
/app/storage/data/{clientId}/on disk for future analytics and export. - Purge Historical Data: Deletes the partition folder and all CSV files for this client permanently.
- Keep Historical Data: Retains
- Tombstone Protection: DataStack records the client ID and secret in the
deleted_clientsPostgreSQL table. Even if someone attempts to reuse an old signed JWT, the ingestion server checks the tombstone list and rejects the request.