yanpgwang
diff --git a/‎README.md‎
Lines changed: 5 additions & 3 deletions b/‎README.md‎
Lines changed: 5 additions & 3 deletions
diff --git a/‎SECURITY.md‎
Lines changed: 10 additions & 2 deletions b/‎SECURITY.md‎
Lines changed: 10 additions & 2 deletions
diff --git a/‎cmd/managed-agent/main.go‎
Lines changed: 157 additions & 7 deletions b/‎cmd/managed-agent/main.go‎
Lines changed: 157 additions & 7 deletions
diff --git a/‎cmd/managed-agent/orchestrate.go‎
Lines changed: 2 additions & 1 deletion b/‎cmd/managed-agent/orchestrate.go‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎deployments/local/README.md‎
Lines changed: 6 additions & 1 deletion b/‎deployments/local/README.md‎
Lines changed: 6 additions & 1 deletion
diff --git a/‎deployments/local/compose.yaml‎
Lines changed: 1 addition & 0 deletions b/‎deployments/local/compose.yaml‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/api/environment-work.md‎
Lines changed: 5 additions & 5 deletions b/‎docs/api/environment-work.md‎
Lines changed: 5 additions & 5 deletions
diff --git a/‎docs/api/overview.md‎
Lines changed: 19 additions & 5 deletions b/‎docs/api/overview.md‎
Lines changed: 19 additions & 5 deletions
diff --git a/‎docs/architecture.md‎
Lines changed: 8 additions & 2 deletions b/‎docs/architecture.md‎
Lines changed: 8 additions & 2 deletions
@@ -40,8 +40,8 @@ production-oriented architecture is built in Go on PostgreSQL and Temporal.
   client-action waits survive API and worker restarts.
 - **Bring your own execution environment.** Choose local, Docker, E2B,
   CubeSandbox, OpenSandbox, or Daytona sandbox adapters.
-- **Run the whole stack locally.** Start a credential-free development stack
-  with an offline model, PostgreSQL, Temporal, NATS, and MinIO.
+- **Run the whole stack locally.** Start without external model credentials;
+  the Compose stack supplies a development-only Mango API key.
 - **Inspect every turn.** Query the persisted event history, stream live
   previews over SSE, and inspect active workflows in Temporal UI.
 
@@ -62,7 +62,9 @@ Verify that Mango is ready:
 curl -i http://localhost:8080/readyz
 ```
 
-The local stack uses a deterministic offline model, so no API key is required.
+The local stack uses a deterministic offline model, so no model API key is
+required. Protected Mango routes use the development key
+`sk-mango-local-development`; health and readiness remain public.
 Follow the [five-minute walkthrough](https://yanpgwang.github.io/managed-agent-go/getting-started)
 to create an Environment, Agent, and Session, then send and stream your first
 message.
 
@@ -29,8 +29,16 @@ maintainer contact without disclosing vulnerability details.
 - The Docker provider gives container isolation and disables networking by
   default, but containers share the host kernel and the provider has not been
   audited for hostile multi-tenant workloads.
-- `-strict` checks that authentication headers are present; it does not
-  validate credentials or implement authorization.
+- Every protected API request is authenticated by an opaque API key and scoped
+  to one Workspace. Top-level resources, child resources, scheduled work, and
+  object-store keys are isolated by that Workspace. Health, readiness, and the
+  embedded OpenAPI document remain public.
+- All keys for one Workspace have identical access to that Workspace. Mango
+  does not model end users, roles, per-resource grants, or user-level audit
+  identity; a SaaS or enterprise control plane must own those concerns and
+  issue or revoke Workspace keys.
+- `-strict` additionally validates CMA version, beta, and content-type headers;
+  it does not change authorization semantics.
 - PostgreSQL journals tool attempts, but an external side effect can still be
   ambiguous if execution succeeds and its durable result is lost. Exactly-once
   behavior requires idempotency from the external system.
 
@@ -391,30 +391,155 @@ func newHTTPServer(addr string, handler http.Handler) *http.Server {
 
 func main() {
 	if len(os.Args) < 2 {
-		log.Fatal("usage: managed-agent <serve|orchestrate> [flags]")
+		log.Fatal("usage: managed-agent <serve|orchestrate|workspace|api-key> [flags]")
 	}
 	switch os.Args[1] {
 	case "serve":
 		runServe()
 	case "orchestrate":
 		runOrchestrate()
+	case "workspace":
+		runWorkspaceCommand()
+	case "api-key":
+		runAPIKeyCommand()
 	default:
-		log.Fatal("usage: managed-agent <serve|orchestrate> [flags]")
+		log.Fatal("usage: managed-agent <serve|orchestrate|workspace|api-key> [flags]")
 	}
 }
 
 func runServe() {
 	fs := flag.NewFlagSet("serve", flag.ExitOnError)
 	addr := fs.String("addr", defaultAddr, "listen address (default binds to loopback; use e.g. :8080 to expose on all interfaces)")
-	strict := fs.Bool("strict", false, "require Claude API wire headers (auth, version, beta, content-type) to be present and valid; this is header validation, NOT authentication")
+	strict := fs.Bool("strict", false, "require Claude API version, beta, and content-type headers; API-key authentication is always enforced")
 	_ = fs.Parse(os.Args[2:])
 
 	cfg := httpapi.Config{
-		RequireBeta: *strict, RequireAuth: *strict, RequireVersion: *strict, RequireContentType: *strict,
+		RequireBeta: *strict, RequireVersion: *strict, RequireContentType: *strict,
 	}
 	runPostgresAPI(*addr, cfg)
 }
 
+func runWorkspaceCommand() {
+	if len(os.Args) < 3 {
+		log.Fatal("usage: managed-agent workspace <create|list> [flags]")
+	}
+	switch os.Args[2] {
+	case "create":
+		fs := flag.NewFlagSet("workspace create", flag.ExitOnError)
+		name := fs.String("name", "", "workspace display name")
+		_ = fs.Parse(os.Args[3:])
+		if err := withOperatorStore(func(ctx context.Context, store *pg.Store) error {
+			item, err := store.CreateWorkspace(ctx, *name)
+			if err != nil {
+				return err
+			}
+			fmt.Printf("%s\t%s\n", item.ID, item.Name)
+			return nil
+		}); err != nil {
+			log.Fatalf("workspace create: %v", err)
+		}
+	case "list":
+		fs := flag.NewFlagSet("workspace list", flag.ExitOnError)
+		_ = fs.Parse(os.Args[3:])
+		if err := withOperatorStore(func(ctx context.Context, store *pg.Store) error {
+			items, err := store.ListWorkspaces(ctx)
+			if err != nil {
+				return err
+			}
+			for _, item := range items {
+				fmt.Printf("%s\t%s\t%s\n", item.ID, item.Name, item.CreatedAt.Format(time.RFC3339))
+			}
+			return nil
+		}); err != nil {
+			log.Fatalf("workspace list: %v", err)
+		}
+	default:
+		log.Fatal("usage: managed-agent workspace <create|list> [flags]")
+	}
+}
+
+func runAPIKeyCommand() {
+	if len(os.Args) < 3 {
+		log.Fatal("usage: managed-agent api-key <create|list|revoke> [flags]")
+	}
+	switch os.Args[2] {
+	case "create":
+		fs := flag.NewFlagSet("api-key create", flag.ExitOnError)
+		workspaceID := fs.String("workspace", "", "workspace ID")
+		label := fs.String("label", "", "operator-visible key label")
+		_ = fs.Parse(os.Args[3:])
+		if strings.TrimSpace(*workspaceID) == "" {
+			log.Fatal("api-key create: -workspace is required")
+		}
+		if err := withOperatorStore(func(ctx context.Context, store *pg.Store) error {
+			item, secret, err := store.CreateAPIKey(ctx, *workspaceID, *label)
+			if err != nil {
+				return err
+			}
+			// The plaintext secret is intentionally emitted only at creation.
+			fmt.Printf("id\t%s\nworkspace\t%s\napi_key\t%s\n", item.ID, item.WorkspaceID, secret)
+			return nil
+		}); err != nil {
+			log.Fatalf("api-key create: %v", err)
+		}
+	case "list":
+		fs := flag.NewFlagSet("api-key list", flag.ExitOnError)
+		workspaceID := fs.String("workspace", "", "workspace ID")
+		_ = fs.Parse(os.Args[3:])
+		if strings.TrimSpace(*workspaceID) == "" {
+			log.Fatal("api-key list: -workspace is required")
+		}
+		if err := withOperatorStore(func(ctx context.Context, store *pg.Store) error {
+			items, err := store.ListAPIKeys(ctx, *workspaceID)
+			if err != nil {
+				return err
+			}
+			for _, item := range items {
+				status := "active"
+				if item.RevokedAt != nil {
+					status = "revoked"
+				}
+				fmt.Printf("%s\t%s\t%s\t%s\n", item.ID, item.Label, status, item.CreatedAt.Format(time.RFC3339))
+			}
+			return nil
+		}); err != nil {
+			log.Fatalf("api-key list: %v", err)
+		}
+	case "revoke":
+		fs := flag.NewFlagSet("api-key revoke", flag.ExitOnError)
+		id := fs.String("id", "", "API key ID")
+		_ = fs.Parse(os.Args[3:])
+		if strings.TrimSpace(*id) == "" {
+			log.Fatal("api-key revoke: -id is required")
+		}
+		if err := withOperatorStore(func(ctx context.Context, store *pg.Store) error {
+			return store.RevokeAPIKey(ctx, *id)
+		}); err != nil {
+			log.Fatalf("api-key revoke: %v", err)
+		}
+		fmt.Printf("revoked\t%s\n", *id)
+	default:
+		log.Fatal("usage: managed-agent api-key <create|list|revoke> [flags]")
+	}
+}
+
+func withOperatorStore(run func(context.Context, *pg.Store) error) error {
+	databaseURL := strings.TrimSpace(os.Getenv(envDatabaseURL))
+	if databaseURL == "" {
+		return fmt.Errorf("%s is required", envDatabaseURL)
+	}
+	ctx := context.Background()
+	pool, err := pg.Pool(ctx, databaseURL)
+	if err != nil {
+		return fmt.Errorf("postgres: %w", err)
+	}
+	defer pool.Close()
+	if err := pg.Migrate(ctx, pool); err != nil {
+		return fmt.Errorf("migrate: %w", err)
+	}
+	return run(ctx, pg.NewSystemStore(pool, domain.NewRandomIDGen(), realClock{}))
+}
+
 func runPostgresAPI(addr string, cfg httpapi.Config) {
 	databaseURL := os.Getenv(envDatabaseURL)
 	if databaseURL == "" {
@@ -433,6 +558,20 @@ func runPostgresAPI(addr string, cfg httpapi.Config) {
 	ids := domain.NewRandomIDGen()
 	clock := realClock{}
 	pgStore := pg.NewStore(pool, ids, clock)
+	if bootstrapKey := strings.TrimSpace(os.Getenv(envAPIKey)); bootstrapKey != "" {
+		if err := pgStore.BootstrapAPIKey(ctx, bootstrapKey); err != nil {
+			log.Fatalf("serve: bootstrap API key: %v", err)
+		}
+	}
+	keyCount, err := pgStore.CountActiveAPIKeys(ctx)
+	if err != nil {
+		log.Fatalf("serve: count API keys: %v", err)
+	}
+	if keyCount == 0 {
+		log.Fatalf("serve: no active API key; set %s or run managed-agent api-key create", envAPIKey)
+	}
+	cfg.Authenticator = pgStore
+	systemStore := pg.NewSystemStore(pool, ids, clock)
 	memory := app.NewMemoryService(pg.NewMemoryRepository(pgStore), ids, clock)
 	vaults, err := resolveVaultService(pgStore, ids, clock)
 	if err != nil {
@@ -468,14 +607,22 @@ func runPostgresAPI(addr string, cfg httpapi.Config) {
 			LimitedNetwork: providerCapabilities.LimitedNetwork,
 		},
 	)
-	fileRuntime, err := resolveFiles(ctx, pgStore, ids, clock, true)
+	fileRuntime, err := resolveFiles(ctx, pgStore, ids, clock, false)
 	if err != nil {
 		log.Printf("serve: Files API disabled: %v", err)
 		fileRuntime = nil
 	} else if fileRuntime == nil {
 		log.Printf("serve: Files API disabled; %s is not configured", fileS3BucketEnv)
 	} else {
-		log.Printf("serve: Files API object store connected and reconciled")
+		fileReconciler := app.NewFileService(
+			pg.NewFileRepository(systemStore), fileRuntime.blobs, ids, clock,
+		)
+		if err := fileReconciler.Reconcile(ctx); err != nil {
+			log.Printf("serve: Files API disabled: reconcile incomplete operations: %v", err)
+			fileRuntime = nil
+		} else {
+			log.Printf("serve: Files API object store connected and reconciled")
+		}
 	}
 	var files *app.FileService
 	var skills *app.SkillService
@@ -486,7 +633,10 @@ func runPostgresAPI(addr string, cfg httpapi.Config) {
 		skills = app.NewSkillService(
 			pg.NewSkillRepository(pgStore), fileRuntime.blobs, ids, clock,
 		)
-		if err := skills.Reconcile(ctx); err != nil {
+		skillReconciler := app.NewSkillService(
+			pg.NewSkillRepository(systemStore), fileRuntime.blobs, ids, clock,
+		)
+		if err := skillReconciler.Reconcile(ctx); err != nil {
 			log.Printf("serve: Skills API disabled: reconcile incomplete operations: %v", err)
 			skills = nil
 		} else {
 
@@ -321,6 +321,7 @@ const (
 	envTemporalHostPort  = "MANAGED_AGENT_TEMPORAL_HOSTPORT"
 	envTemporalNamespace = "MANAGED_AGENT_TEMPORAL_NAMESPACE"
 	envNATSURL           = "MANAGED_AGENT_NATS_URL"
+	envAPIKey            = "MANAGED_AGENT_API_KEY"
 )
 
 // runOrchestrate boots the Temporal execution role: it runs PostgreSQL
@@ -346,7 +347,7 @@ func runOrchestrate() {
 	log.Printf("orchestrate: postgres connected and migrated")
 
 	ids := domain.NewRandomIDGen()
-	store := pg.NewStore(pool, ids, realClock{})
+	store := pg.NewSystemStore(pool, ids, realClock{})
 	vaults, err := resolveVaultService(store, ids, realClock{})
 	if err != nil {
 		log.Fatalf("orchestrate: Vault runtime keyring: %v", err)
 
@@ -31,6 +31,10 @@ When `~/.config/mango/dev.env` exists, `make local-up` loads it via
 worker uses the real Messages endpoint. A missing file or empty model values
 keep the offline deterministic model.
 
+The API bootstraps `sk-mango-local-development` for the default Workspace.
+Override it with `MANAGED_AGENT_API_KEY` before `make local-up`; never reuse the
+bundled value outside local development.
+
 `make health` returns only once Postgres accepts connections, the Temporal
 frontend answers `cluster health`, NATS `/healthz` is green, MinIO answers its
 live probe, the API answers `/readyz`, and the worker process is alive.
@@ -47,6 +51,7 @@ docker compose -f deployments/local/compose.yaml ps
 ```sh
 # Application database (pgx / goose / sqlc)
 export MANAGED_AGENT_DATABASE_URL="postgres://postgres:postgres@localhost:5432/managed_agent?sslmode=disable"
+export MANAGED_AGENT_API_KEY="sk-mango-local-development"
 
 # Temporal frontend (Go SDK client)
 export MANAGED_AGENT_TEMPORAL_HOSTPORT="localhost:7233"
@@ -110,7 +115,7 @@ make local-down VOLUMES=1  # also delete the Postgres and MinIO volumes
 
 This stack is for local development and integration tests only. It already
 keeps API and worker process roles separate, but it is not a production
-deployment manifest: authentication, TLS, secrets, rolling worker versioning,
+deployment manifest: end-user authorization, TLS, secrets, rolling worker versioning,
 managed persistence, observability, resource limits, and production object
 storage remain deployment work. The bundled MinIO credentials and deterministic
 Vault keyring are not a production recommendation. Files startup reconciliation
 
@@ -125,6 +125,7 @@ services:
         condition: service_healthy
     environment:
       MANAGED_AGENT_DATABASE_URL: postgres://postgres:postgres@postgres:5432/managed_agent?sslmode=disable
+      MANAGED_AGENT_API_KEY: ${MANAGED_AGENT_API_KEY:-sk-mango-local-development}
       MANAGED_AGENT_TEMPORAL_HOSTPORT: temporal:7233
       MANAGED_AGENT_TEMPORAL_NAMESPACE: default
       MANAGED_AGENT_NATS_URL: nats://nats:4222
 
@@ -59,10 +59,10 @@ object store are configured.
 ## Security boundary
 
 The official worker sends an Environment key as a bearer credential for Work,
-Session, event, and Skill requests. Mango strict mode currently checks only
-that an API key or bearer header is present; it does not issue Environment keys
-or scope them to one Environment. Work `secret` is therefore returned as
-`null`. Put authentication, tenant isolation, and environment-scoped
-authorization in front of this surface before production exposure.
+Session, event, and Skill requests. Mango authenticates that credential as a
+Workspace API key and limits all of those resources to the same Workspace. It
+does not issue narrower Environment-worker credentials, so Work `secret`
+remains `null`. A surrounding control plane should add Environment-specific
+policy before exposing this surface to untrusted workers.
 
 See [API compatibility](../compatibility.md) for the current support boundary.
@@ -54,11 +54,12 @@ Resource-specific request shapes are covered in:
 
 ## Headers
 
-The default development server accepts requests without compatibility headers.
-Run with `-strict` to require them:
+Every protected route requires an API key. The default development stack uses
+`sk-mango-local-development`. Run with `-strict` to additionally require the
+CMA compatibility headers:
 
 ```http
-x-api-key: any-non-empty-value
+x-api-key: sk-mango-local-development
 anthropic-version: 2023-06-01
 anthropic-beta: managed-agents-2026-04-01
 content-type: application/json
@@ -79,8 +80,21 @@ continues to use the Managed Agents beta when attaching a Memory Store.
 Dreams require the separate `dreaming-2026-04-21` preview upstream. Mango does
 not currently serve `/v1/dreams` or claim the v1.63.1 `output_behavior` union.
 
-`authorization` may replace `x-api-key`. Strict mode currently validates header
-presence and version/beta values; it is not a production authentication system.
+`authorization: Bearer <key>` may replace `x-api-key`, but sending both is an
+authentication error. Each key resolves to exactly one Workspace, and every
+key for that Workspace can access the same resources. Workspace IDs are not
+added to CMA request or response bodies.
+
+Mango intentionally has no end-user or role model. A surrounding SaaS may map
+many users to a Workspace and apply its own RBAC before calling Mango. Use the
+operator CLI to manage the OSS boundary:
+
+```sh
+managed-agent workspace create -name acme
+managed-agent api-key create -workspace wrkspc_... -label production
+managed-agent api-key list -workspace wrkspc_...
+managed-agent api-key revoke -id key_...
+```
 
 Every response includes a `request-id` header. JSON request bodies are limited
 to 32 MiB and unknown top-level fields are rejected. A file upload is limited
 
@@ -17,6 +17,11 @@ Provider sandbox bindings and File/Skill lifecycle intents are persisted in
 PostgreSQL; File bytes and immutable custom Skill archives live in object
 storage when those optional surfaces are enabled.
 
+The HTTP edge authenticates opaque API keys into a single Workspace tenant
+scope. PostgreSQL roots, asynchronous execution, and object keys preserve that
+scope; end-user identity and enterprise RBAC remain outside Mango. See
+[Workspace tenancy](architecture/workspace-tenancy.md).
+
 ```mermaid
 flowchart LR
   Client["Managed Agents client"] --> API["HTTP API"]
@@ -188,8 +193,9 @@ The strongest current risks are semantic rather than structural:
    create-before-binding crash window and workers autonomously resume fenced
    deletions. Provider-aware routing for heterogeneous workers, quotas, and
    eviction are not implemented.
-3. Worker Versioning, observability, authentication, large-payload offload, and
-   production manifests remain open.
+3. Worker Versioning, observability, enterprise identity/RBAC, large-payload
+   offload, and production manifests remain open. The OSS Workspace API-key
+   and tenant-isolation boundary is implemented.
 4. Provider Transcript, native Web Search/Fetch, sandbox result
    materialization, and unauthenticated MCP tools are implemented. Context
    Snapshots, provider-round records, deployment-managed MCP authentication, and