Backend Developer Guide

Backend Developer Guide

This guide documents the implemented Backend service in harden-v2/src/Backend.

The Backend service is the system of record for:

  • organizations, plans, and billing metadata
  • org admins and user accounts
  • encrypted key/value metadata and audit history
  • encrypted file metadata
  • trusted-user recovery shares
  • per-org S3-compatible file storage configuration

Base Endpoint

  • Dev admin endpoint: https://dev2-admin-api.harden.cloud
  • Authenticated routes use: X-Api-Key: <api_key>
  • Anonymous auth routes live under /auth/*

Implemented Feature Set

  • Public plan catalog and org-admin self-registration.
  • Email verification and password login for org admins.
  • Global admin org bootstrap flows.
  • Org admin user creation and API key rotation.
  • Per-org file storage configuration for paid plans.
  • User profile, key material, org user discovery, and trusted-user recovery APIs.
  • Encrypted KV metadata, encrypted file metadata, and audit retrieval.
  • File-backed state by default, with Postgres-backed runtime when configured.

Authentication Model

Anonymous routes

  • GET /auth/plans
  • POST /auth/orgadmin/register
  • GET /auth/orgadmin/verify
  • POST /auth/orgadmin/login
  • GET /health

API-key routes

  • Admin routes under /admin/*
  • User routes under /users/*
  • KV, file, and audit routes

Authorization is enforced in handlers:

  • global admin only: org creation and org listing
  • org admin or global admin: user lifecycle and storage configuration
  • any authenticated user: profile, key material, org user discovery, recovery, KV, and file routes
  • org admin only: /audit

API Reference And Examples

Runtime And Storage

  • Framework: ASP.NET Core on .NET 10
  • Default state store: JSON files under BACKEND_DATA_ROOT or data/backend
  • Postgres mode: enabled with POSTGRES_CONNECTION or POSTGRES_CONNECTION_STRING
  • File objects: stored in S3-compatible storage configured per org

Key Environment Variables

Core runtime

  • POSTGRES_CONNECTION
  • POSTGRES_CONNECTION_STRING
  • BACKEND_DATA_ROOT
  • BOOTSTRAP_ADMIN_KEY_PATH

Email verification

  • ORGADMIN_VERIFY_URL_BASE
  • POSTMARK_SERVER_TOKEN
  • POSTMARK_FROM_EMAIL
  • SMTP_HOST
  • SMTP_PORT
  • SMTP_ENABLE_SSL
  • SMTP_USERNAME
  • SMTP_PASSWORD
  • SMTP_FROM_EMAIL

Billing

  • STRIPE_SECRET_KEY
  • STRIPE_PRICE_CURRENCY

Notes

  • On first startup with an empty state store, Backend creates a default org and a global admin user, then writes the bootstrap admin API key to BOOTSTRAP_ADMIN_KEY_PATH or /etc/harden/bootstrap-admin.key.
  • GET /admin/orgs/{orgId}/storage never returns the raw secretKey; it returns hasSecretKey instead.
  • Updating storage config can preserve the existing secret by omitting secretKey when a secret is already stored.