Roadmap relationship
Outcome
Give CI systems and external automation a stable, documented, least-privilege API backed by the same service layer, authorization, validation, operation records, and audit behavior as the dashboard and CLI.
Current gap
The dashboard exposes internal JSON endpoints and the CLI calls implementation-specific helpers, but there is no versioned public API contract, scoped machine identity, token lifecycle, idempotency standard, or generated client.
User experience
- Add an automation settings page showing token name, scopes, resource limits, creator, created/last-used/expiry times, and one-time secret reveal.
- Provide copyable CLI/curl examples and clear expired, revoked, forbidden, rate-limited, and idempotent-replay responses.
- Show API-originated operations in the same deployment/activity timeline as dashboard and CLI actions.
Scope
- Model service accounts and hashed API tokens with explicit organization/resource scopes, expiry, rotation, revoke, and last-use metadata.
- Define
/api/v1resources for projects, environments, services, deployments, operations, logs/events, and later area-specific resources. - Generate an OpenAPI document and TypeScript client/CLI bindings from shared schemas.
- Add cursor pagination, stable error envelopes, request IDs, idempotency keys, rate limits, and webhook/event subscription guidance.
Technical direction
- Extract application services from HTTP route handlers so dashboard, CLI, and API share behavior.
- Version schemas and document additive/breaking-change policy.
- Stream long-running progress through an authenticated event endpoint while mutation responses return operation IDs.
- Redact sensitive fields at serialization boundaries and annotate secret write-only properties.
Safety and operability
- Never store or re-display raw tokens after creation; support overlap during rotation.
- Enforce scopes and resource boundaries on every request and stream subscription.
- Audit token creation/use/rotation/revoke without logging credentials.
- Require idempotency for retry-prone destructive or billable operations.
Acceptance criteria
- CI can deploy one environment with a token that cannot read secrets, manage users, or access other environments.
- Equivalent CLI, API, and dashboard actions create the same operation/event shape and authorization result.
- The OpenAPI document passes validation and examples run against a test server.
- Revoked or expired tokens stop working immediately and pagination remains stable.
Verification
- Scope matrix, rotation overlap, expiry, replay/idempotency, rate-limit, pagination, and redaction tests.
- Contract tests generated from OpenAPI plus CLI/API parity tests.
- End-to-end CI-style deployment using only a service account token.
Non-goals
- Guaranteeing indefinite compatibility for undocumented internal endpoints.
- Giving API tokens interactive browser sessions.
- Exposing arbitrary shell execution as a generic API method.