Future SDK & HTTP API Design
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Barekey is designed as a developer-first SaaS vault manager, prioritizing high-tier developer experience (DX) for managing encrypted environment variables and secrets. While the current implementation primarily uses a React SPA communicating directly with a Convex backend via WebSockets, the architecture explicitly reserves space for a future ecosystem involving a CLI and various SDKs.
The scope of this design involves transitioning internal Convex logic—currently used by the UI—into public-facing HTTP endpoints. These endpoints will facilitate remote secret retrieval, project configuration, and automated deployment flows. The system relies on a robust envelope encryption model and a strict slug-based routing policy to ensure secure and predictable access across different platforms.
Sources: AGENTS.md:3-10, AGENTS.md:27-30
Architecture and Core Components
The future SDK and HTTP API will be hosted on Convex via the pkg/convex/http.ts entry point. This layer will act as the gateway for external clients (CLI/SDKs) to interact with the underlying vault and project management logic.
System Interaction Flow
The following diagram illustrates how external SDKs and the CLI will interact with the Convex backend compared to the existing SPA.
The Convex backend serves as the unified host for both real-time UI interactions and stateless HTTP requests.
Sources: AGENTS.md:25-35
Authentication and Security
External access via SDKs and the CLI will mirror the security posture of the SPA. Requests must validate against Clerk-managed identities.
- JWT Validation: HTTP endpoints will validate Clerk JWTs to identify the user and their associated organization (team).
- Organization-Only Ownership: Only teams (orgs) can own projects; the API will not support individual user ownership for vault resources.
- Envelope Encryption: The API will interact with the multi-layered encryption system where a Master KEK (Key Encryption Key) protects per-project DEKs (Data Encryption Keys), which in turn encrypt individual secret values.
Sources: AGENTS.md:42-49, AGENTS.md:61-68
Configuration and Runtime Targeting
For SDKs and the CLI to function, they require a specific runtime configuration file, currently scaffolded in the UI as barekey.json. This file provides the necessary identifiers for the API to resolve requests.
Runtime Configuration Fields
| Field | Type | Description |
|---|---|---|
apiUrl | String | The base URL for the Barekey API (e.g., https://api.barekey.dev). |
orgSlug | String | The unique, alphanumeric identifier of the organization. |
projectSlug | String | The unique identifier for the project within the org. |
environmentSlug | String | The stage (e.g., development, production) to fetch variables from. |
Sources: pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:431-438, pkg/ui/src/pages/o/[org]/project/[projectSlug]/variables/page.tsx:870-877
Planned API Functionality
The API will expose functions currently implemented as internal Convex mutations and queries. Key areas of focus include:
1. Secret Retrieval (SDK Focus)
The primary use case for the SDK is fetching decrypted secrets for application runtimes.
- Logic: The API must resolve the
projectSlugandstageSlugto find the correctprojectVariables. - Security: Values are stored encrypted; the API will perform a per-request unwrap of the DEK to decrypt values before returning them to the authorized SDK client.
Sources: pkg/convex/project_variables.ts:40-45, pkg/convex/project_variables.ts:252-270
2. Variable Management (CLI Focus)
The CLI will likely support bulk operations for CI/CD pipelines, utilizing logic found in applyDraftForCurrentOrgProjectStage.
Bulk operations allow for atomic updates, ensuring that partial failures do not leave environment configurations in an inconsistent state.
Sources: pkg/convex/project_variables.ts:107-130
3. Stage and Project Lifecycle
The API will provide endpoints to manage the environment hierarchy (Development, Staging, Production).
- Immutability: While display names can be changed, stage slugs are intentionally immutable to prevent breaking SDK/CLI references in production environments.
- Cleanup Guards: Endpoints for deletion (e.g.,
deleteForCurrentOrgProject) will include guards that block deletion if the resource still contains variables or environments.
Sources: pkg/convex/project_stages.ts:192-200, pkg/convex/projects.ts:182-195, pkg/ui/src/pages/o/[org]/project/[projectSlug]/settings/page.tsx:187-190
Data Models and Constraints
API requests must adhere to the project's strict slug and naming policies to maintain consistency across the ecosystem.
| Resource | Field | Constraint |
|---|---|---|
| Project | Name | 1-120 characters, trimmed. |
| Project | Slug | Alphanumeric ^[a-z0-9]+$, maximum 48 characters. |
| Stage | Name | 1-64 characters. |
| Variable | Name | 1-160 characters. |
| Variable | Kind | Currently restricted to secret. |
Sources: AGENTS.md:52-57, pkg/convex/projects.ts:110-115, pkg/convex/project_stages.ts:145-150, pkg/convex/project_variables.ts:15-20
Conclusion
The Future SDK & HTTP API design leverages the existing robust Convex backend to provide programmatic access to the Barekey vault. By formalizing the transition from UI-based Convex functions to public HTTP endpoints, Barekey will enable automated secret management, secure CI/CD integration, and flexible application runtimes while maintaining the core security principles of envelope encryption and organization-based access control.