API Endpoints & Routing
Relevant source files
The following files were used as context for generating this wiki page:
The SecretForge AI API is a Cloudflare Workers-based service built using the Hono framework. It serves as the central orchestration layer for secret management, AI-powered project analysis, and compliance validation. The API provides a secure interface for the CLI, Web Dashboard, and Model Context Protocol (MCP) server to interact with persistent storage (D1), secret vaults (KV), and vector databases for documentation search.
The routing architecture is designed for global low-latency deployment, leveraging Cloudflare's edge network. It incorporates strict Zod-based schema validation, JWT and API key authentication, and tier-based rate limiting to ensure secure and efficient access to secret management features.
Sources: README.md:46-75, WARP.md:57-60, packages/api/src/tests/api.integration.test.ts:10-25
Authentication & Middleware
The API implements a multi-layered authentication strategy. Requests are validated using either a JSON Web Token (JWT) provided in the Authorization header or a platform-specific API key provided in the X-API-Key header.
Authentication Flow
The following diagram illustrates the authentication middleware logic applied to incoming requests.
The system distinguishes between user tiers (e.g., free, pro) during the authentication phase to enforce feature access controls and rate limits. For instance, AI features are restricted based on the user's subscription tier.
Sources: packages/api/src/tests/api.integration.test.ts:47-75, packages/api/src/tests/api.integration.test.ts:188-218
Core API Endpoints
The API is organized into several functional groups: Authentication, Secret Management, Project Analysis, and AI/Agent interactions.
Authentication Endpoints
These endpoints handle user lifecycle and session management.
| Endpoint | Method | Description | Validation Schema |
|---|---|---|---|
/auth/signup | POST | Creates a new user account with email and password. | createUserSchema |
/auth/login | POST | Authenticates user and returns a JWT. | loginSchema |
/health | GET | Returns the system health status and timestamp. | N/A |
Sources: packages/api/src/tests/api.integration.test.ts:40-45, packages/api/src/tests/api.integration.test.ts:77-111, packages/api/src/schemas/validation.ts:6-21
Secret Management Endpoints
These endpoints provide CRUD operations and lifecycle management for encrypted secrets. Secrets are stored in the SECRETS_VAULT (KV) while metadata resides in the D1 database.
| Endpoint | Method | Description | Parameters |
|---|---|---|---|
/api/secrets | GET | List all secrets for the authenticated user. | N/A |
/api/secrets | POST | Create a new secret for a specific service and environment. | service, environment, scopes |
/api/secrets/:id | GET | Retrieve the decrypted value and metadata of a secret. | id (path) |
/api/secrets/:id/rotate | POST | Trigger an AI-powered rotation for the specified secret. | gracePeriodHours |
/api/secrets/:id/validate | GET | Validate secret against compliance frameworks (e.g., SOC2). | framework (query) |
/api/secrets/:id | DELETE | Permanently remove a secret from the vault. | id (path) |
Sources: packages/api/src/tests/api.integration.test.ts:113-176, packages/api/src/schemas/validation.ts:26-47
AI & Analysis Endpoints
Endpoints that leverage Cloudflare Agents and Vectorize for intelligent operations.
| Endpoint | Method | Description | Data Structure |
|---|---|---|---|
/api/analyze | POST | Analyzes project dependencies to detect required services. | dependencies (Record) |
/api/agent/chat | POST | Stateful AI chat for secret management assistance. | message (string) |
/api/docs/search | GET | Semantic search across service documentation. | service, q (query) |
Sources: packages/api/src/tests/api.integration.test.ts:178-186, packages/api/src/tests/api.integration.test.ts:192-200, packages/mcp-server/src/index.ts:251-255
Request Validation Architecture
SecretForge AI utilizes Zod for strict runtime type checking and validation of all incoming request bodies and parameters. This ensures that only well-formatted data reaches the business logic layer.
Secret Creation Sequence
The following sequence diagram demonstrates the interaction between the API, the validation layer, and the storage backends during secret creation.
Error Handling & Status Codes
The API employs a standardized error response format to ensure consistency across clients. Errors include an error code, message, and timestamp.
| Status Code | Meaning | Context |
|---|---|---|
| 200 | OK | Successful retrieval or update. |
| 201 | Created | Successful creation of a secret or user. |
| 400 | Bad Request | Validation failure (e.g., weak password or missing fields). |
| 401 | Unauthorized | Missing or invalid JWT/API Key. |
| 403 | Forbidden | Tier-based restriction (e.g., Free tier accessing AI features). |
| 404 | Not Found | Requested secret ID does not exist. |
| 429 | Too Many Requests | Rate limit exceeded for the current user tier. |
Sources: packages/api/src/tests/api.integration.test.ts:219-253, packages/api/src/schemas/validation.ts:7-14
MCP Server Integration
The MCP (Model Context Protocol) server acts as a specialized proxy that maps natural language tools to specific API routes. It uses stdio transport to communicate with AI assistants like Claude.
Tool-to-Route Mapping
The MCP server translates assistant tool calls into standard HTTP requests to the Cloudflare API.
| MCP Tool Name | Target API Route | Method |
|---|---|---|
analyze_project | /api/analyze | POST |
create_secret | /api/secrets | POST |
rotate_secret | /api/secrets/:id/rotate | POST |
validate_security | /api/secrets/:id/validate | GET |
search_docs | /api/docs/search | GET |
Sources: packages/mcp-server/src/index.ts:55-135, packages/mcp-server/src/index.ts:233-264
The routing and endpoint structure of SecretForge AI provides a robust foundation for secure secret lifecycle management. By offloading heavy AI analysis to stateful Cloudflare Agents and maintaining a clear separation between metadata (D1) and sensitive values (KV), the API achieves high security and scalability.