openapi: 3.0.3 info: title: Insforge Secrets API version: 1.0.0 description: >- Secure secrets management for storing API keys, tokens, and sensitive configuration paths: /api/secrets: get: summary: List all secrets description: Returns metadata for all secrets (without values) tags: - Admin security: - bearerAuth: [] responses: '200': description: List of secret metadata content: application/json: schema: type: object properties: secrets: type: array items: $ref: '#/components/schemas/SecretMetadata' example: secrets: - id: 123e4567-e89b-12d3-a456-426614174000 key: STRIPE_API_KEY isActive: true isReserved: false createdAt: '2024-01-21T10:30:00Z' updatedAt: '2024-01-21T10:30:00Z' expiresAt: null - id: 223e4567-e89b-12d3-a456-426614174001 key: OPENAI_API_KEY isActive: true isReserved: true createdAt: '2024-01-20T09:15:00Z' updatedAt: '2024-01-20T09:15:00Z' expiresAt: '2025-01-20T09:15:00Z' '401': description: Unauthorized '403': description: Forbidden - Admin only post: summary: Create a new secret description: Create a new encrypted secret with a unique key tags: - Admin security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - key - value properties: key: type: string pattern: ^[A-Z0-9_]+$ description: >- Unique key identifier (uppercase letters, numbers, underscores only) example: STRIPE_API_KEY value: type: string description: Secret value to be encrypted example: sk_live_... isReserved: type: boolean default: false description: Whether the secret is protected from deletion expiresAt: type: string format: date-time nullable: true description: Optional expiration date for the secret responses: '201': description: Secret created successfully content: application/json: schema: type: object properties: success: type: boolean message: type: string id: type: string format: uuid example: success: true message: Secret STRIPE_API_KEY has been created successfully id: 123e4567-e89b-12d3-a456-426614174000 '400': description: Invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingFields: value: error: INVALID_INPUT message: Both key and value are required statusCode: 400 invalidKeyFormat: value: error: INVALID_INPUT message: >- Invalid key format. Use uppercase letters, numbers, and underscores only (e.g., STRIPE_API_KEY) statusCode: 400 '409': description: Secret already exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: INVALID_INPUT message: 'Secret already exists: STRIPE_API_KEY' statusCode: 409 /api/secrets/{key}: get: summary: Get secret value description: Retrieve the decrypted value of a specific secret by its key tags: - Admin security: - bearerAuth: [] parameters: - name: key in: path required: true schema: type: string pattern: ^[A-Z0-9_]+$ description: Secret key identifier example: STRIPE_API_KEY responses: '200': description: Secret value retrieved content: application/json: schema: type: object properties: key: type: string value: type: string example: key: STRIPE_API_KEY value: sk_live_... '401': description: Unauthorized '403': description: Forbidden - Admin only '404': description: Secret not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: NOT_FOUND message: 'Secret not found: INVALID_KEY' statusCode: 404 put: summary: Update secret description: Update an existing secret's value or metadata tags: - Admin security: - bearerAuth: [] parameters: - name: key in: path required: true schema: type: string pattern: ^[A-Z0-9_]+$ description: Secret key identifier example: STRIPE_API_KEY requestBody: required: true content: application/json: schema: type: object properties: value: type: string description: New secret value (will be encrypted) isActive: type: boolean description: Whether the secret is active isReserved: type: boolean description: Whether the secret is protected from deletion expiresAt: type: string format: date-time nullable: true description: Expiration date (null to remove expiration) responses: '200': description: Secret updated successfully content: application/json: schema: type: object properties: success: type: boolean message: type: string example: success: true message: Secret STRIPE_API_KEY has been updated successfully '404': description: Secret not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: NOT_FOUND message: 'Secret not found: INVALID_KEY' statusCode: 404 '500': description: Failed to update secret content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: INTERNAL_ERROR message: 'Failed to update secret: STRIPE_API_KEY' statusCode: 500 delete: summary: Delete secret description: Mark a secret as inactive (soft delete). Cannot delete reserved secrets. tags: - Admin security: - bearerAuth: [] parameters: - name: key in: path required: true schema: type: string pattern: ^[A-Z0-9_]+$ description: Secret key identifier example: STRIPE_API_KEY responses: '200': description: Secret deleted successfully content: application/json: schema: type: object properties: success: type: boolean message: type: string example: success: true message: Secret STRIPE_API_KEY has been deleted successfully '403': description: Cannot delete reserved secret content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: FORBIDDEN message: 'Cannot delete reserved secret: OPENAI_API_KEY' statusCode: 403 '404': description: Secret not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: NOT_FOUND message: 'Secret not found: INVALID_KEY' statusCode: 404 components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: SecretMetadata: type: object properties: id: type: string format: uuid description: Unique identifier for the secret key: type: string description: Unique key identifier (uppercase with underscores) example: STRIPE_API_KEY isActive: type: boolean description: Whether the secret is currently active isReserved: type: boolean description: Whether the secret is protected from deletion createdAt: type: string format: date-time description: When the secret was created updatedAt: type: string format: date-time description: When the secret was last updated expiresAt: type: string format: date-time nullable: true description: When the secret expires (null if no expiration) required: - id - key - isActive - isReserved - createdAt - updatedAt ErrorResponse: type: object required: - error - message - statusCode properties: error: type: string description: Error code for programmatic handling example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid input data statusCode: type: integer description: HTTP status code example: 400 nextActions: type: string description: Suggested action to resolve the error example: Check the request body format