feat: admin secrets provisioning API + API documentation

- Add PUT/GET/DELETE /api/admin/users/{id}/secrets/{name} endpoints for
  application backends to provision per-user secrets (AES-256-GCM encrypted)
- Add secrets_store field to GatewayState with builder wiring
- Create docs/USER_MANAGEMENT_API.md with full API spec covering users,
  secrets, tokens, profile, and usage endpoints
- Update web gateway CLAUDE.md route table

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

src/channels/web/CLAUDE.md

@@ -91,6 +91,34 @@ Browser-facing HTTP API and SSE/WebSocket real-time streaming. Axum-based, singl
 | DELETE | `/api/routines/{id}` | Delete a routine |
 | GET | `/api/routines/{id}/runs` | List runs for a specific routine |
 
+### User Management (admin — requires `admin` role, see `docs/USER_MANAGEMENT_API.md`)
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/admin/users` | Create a new user (returns one-time token) |
+| GET | `/api/admin/users` | List all users |
+| GET | `/api/admin/users/{id}` | Get a single user |
+| PATCH | `/api/admin/users/{id}` | Update user profile/metadata |
+| DELETE | `/api/admin/users/{id}` | Delete user and all data |
+| POST | `/api/admin/users/{id}/suspend` | Suspend a user |
+| POST | `/api/admin/users/{id}/activate` | Re-activate a user |
+| GET | `/api/admin/usage` | Per-user LLM usage stats |
+| GET | `/api/admin/users/{id}/secrets` | List a user's secrets (names only) |
+| PUT | `/api/admin/users/{id}/secrets/{name}` | Create or update a user's secret |
+| DELETE | `/api/admin/users/{id}/secrets/{name}` | Delete a user's secret |
+
+### Profile (self-service)
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/profile` | Get own profile |
+| PATCH | `/api/profile` | Update own display name/metadata |
+
+### Tokens (self-service)
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/tokens` | Create API token (returns plaintext once) |
+| GET | `/api/tokens` | List own tokens |
+| DELETE | `/api/tokens/{id}` | Revoke a token |
+
 ### Settings
 | Method | Path | Description |
 |--------|------|-------------|

src/channels/web/handlers/mod.rs

@@ -5,6 +5,7 @@
 pub mod jobs;
 pub mod memory;
 pub mod routines;
+pub mod secrets;
 pub mod skills;
 pub mod tokens;
 pub mod users;

src/channels/web/handlers/secrets.rs

@@ -0,0 +1,133 @@
+//! Admin secrets provisioning handlers.
+//!
+//! Allows an admin (typically an application backend) to create, list, and
+//! delete secrets on behalf of individual users so their IronClaw agent can
+//! call back to external services with per-user credentials.
+
+use std::sync::Arc;
+
+use axum::{
+    Json,
+    extract::{Path, State},
+    http::StatusCode,
+};
+
+use crate::channels::web::auth::AdminUser;
+use crate::channels::web::server::GatewayState;
+use crate::secrets::CreateSecretParams;
+
+/// PUT /api/admin/users/{user_id}/secrets/{name} — create or update a secret.
+///
+/// Upserts: if a secret with the same (user_id, name) already exists it is
+/// overwritten. The plaintext value is encrypted at rest (AES-256-GCM) and
+/// never returned by any endpoint.
+pub async fn secrets_put_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+    Path((user_id, name)): Path<(String, String)>,
+    Json(body): Json<serde_json::Value>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let secrets = state.secrets_store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Secrets store not available".to_string(),
+    ))?;
+
+    let value = body
+        .get("value")
+        .and_then(|v| v.as_str())
+        .ok_or((
+            StatusCode::BAD_REQUEST,
+            "Missing required field 'value'".to_string(),
+        ))?
+        .to_string();
+
+    let provider = body
+        .get("provider")
+        .and_then(|v| v.as_str())
+        .map(String::from);
+
+    let expires_at = body
+        .get("expires_in_days")
+        .and_then(|v| v.as_u64())
+        .map(|days| chrono::Utc::now() + chrono::Duration::days(days as i64));
+
+    let mut params = CreateSecretParams::new(name.clone(), value);
+    if let Some(p) = provider {
+        params = params.with_provider(p);
+    }
+    if let Some(exp) = expires_at {
+        params = params.with_expiry(exp);
+    }
+
+    secrets
+        .create(&user_id, params)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(serde_json::json!({
+        "user_id": user_id,
+        "name": name.to_lowercase(),
+        "status": "created",
+    })))
+}
+
+/// GET /api/admin/users/{user_id}/secrets — list a user's secrets (names only).
+///
+/// Never returns secret values or hashes.
+pub async fn secrets_list_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+    Path(user_id): Path<String>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let secrets = state.secrets_store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Secrets store not available".to_string(),
+    ))?;
+
+    let refs = secrets
+        .list(&user_id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    let secrets_json: Vec<serde_json::Value> = refs
+        .into_iter()
+        .map(|r| {
+            serde_json::json!({
+                "name": r.name,
+                "provider": r.provider,
+            })
+        })
+        .collect();
+
+    Ok(Json(serde_json::json!({
+        "user_id": user_id,
+        "secrets": secrets_json,
+    })))
+}
+
+/// DELETE /api/admin/users/{user_id}/secrets/{name} — delete a user's secret.
+pub async fn secrets_delete_handler(
+    State(state): State<Arc<GatewayState>>,
+    AdminUser(_admin): AdminUser,
+    Path((user_id, name)): Path<(String, String)>,
+) -> Result<Json<serde_json::Value>, (StatusCode, String)> {
+    let secrets = state.secrets_store.as_ref().ok_or((
+        StatusCode::SERVICE_UNAVAILABLE,
+        "Secrets store not available".to_string(),
+    ))?;
+
+    let deleted = secrets
+        .delete(&user_id, &name)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    if !deleted {
+        return Err((StatusCode::NOT_FOUND, "Secret not found".to_string()));
+    }
+
+    Ok(Json(serde_json::json!({
+        "user_id": user_id,
+        "name": name,
+        "deleted": true,
+    })))
+}

src/channels/web/mod.rs

@@ -116,6 +116,7 @@ impl GatewayChannel {
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
             active_config: server::ActiveConfigSnapshot::default(),
+            secrets_store: None,
         });
 
         Self {
@@ -169,6 +170,7 @@ impl GatewayChannel {
             routine_engine: Arc::clone(&self.state.routine_engine),
             startup_time: self.state.startup_time,
             active_config: self.state.active_config.clone(),
+            secrets_store: self.state.secrets_store.clone(),
         };
         mutate(&mut new_state);
         self.state = Arc::new(new_state);
@@ -292,6 +294,15 @@ impl GatewayChannel {
         self
     }
 
+    /// Inject the secrets store for admin secret provisioning.
+    pub fn with_secrets_store(
+        mut self,
+        store: Arc<dyn crate::secrets::SecretsStore + Send + Sync>,
+    ) -> Self {
+        self.rebuild_state(|s| s.secrets_store = Some(store));
+        self
+    }
+
     /// Inject the per-user workspace pool for multi-user mode.
     pub fn with_workspace_pool(mut self, pool: Arc<server::WorkspacePool>) -> Self {
         self.rebuild_state(|s| s.workspace_pool = Some(pool));

src/channels/web/server.rs

@@ -16,7 +16,7 @@ use axum::{
         IntoResponse,
         sse::{Event, KeepAlive, Sse},
     },
-    routing::{get, post},
+    routing::{get, post, put},
 };
 use serde::Deserialize;
 use sha2::{Digest, Sha256};
@@ -378,6 +378,8 @@ pub struct GatewayState {
     pub startup_time: std::time::Instant,
     /// Snapshot of active (resolved) configuration for the frontend.
     pub active_config: ActiveConfigSnapshot,
+    /// Secrets store for admin secret provisioning.
+    pub secrets_store: Option<Arc<dyn crate::secrets::SecretsStore + Send + Sync>>,
 }
 
 /// Start the gateway HTTP server.
@@ -532,6 +534,16 @@ pub async fn start_server(
             "/api/admin/users/{id}/activate",
             post(super::handlers::users::users_activate_handler),
         )
+        // Admin secrets provisioning (per-user)
+        .route(
+            "/api/admin/users/{user_id}/secrets",
+            get(super::handlers::secrets::secrets_list_handler),
+        )
+        .route(
+            "/api/admin/users/{user_id}/secrets/{name}",
+            put(super::handlers::secrets::secrets_put_handler)
+                .delete(super::handlers::secrets::secrets_delete_handler),
+        )
         // Usage reporting (admin)
         .route(
             "/api/admin/usage",
@@ -3041,6 +3053,7 @@ mod tests {
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
             active_config: ActiveConfigSnapshot::default(),
+            secrets_store: None,
         })
     }
 

src/channels/web/test_helpers.rs

@@ -92,6 +92,7 @@ impl TestGatewayBuilder {
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
             active_config: crate::channels::web::server::ActiveConfigSnapshot::default(),
+            secrets_store: None,
         })
     }
 

src/channels/web/tests/multi_tenant.rs

@@ -84,6 +84,7 @@ fn build_state(
         routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
         startup_time: std::time::Instant::now(),
         active_config: ActiveConfigSnapshot::default(),
+        secrets_store: None,
     })
 }
 

src/channels/web/ws.rs

@@ -535,6 +535,7 @@ mod tests {
             routine_engine: Arc::new(tokio::sync::RwLock::new(None)),
             startup_time: std::time::Instant::now(),
             active_config: crate::channels::web::server::ActiveConfigSnapshot::default(),
+            secrets_store: None,
         }
     }
 }

src/main.rs

@@ -632,6 +632,9 @@ async fn async_main() -> anyhow::Result<()> {
         if let Some(ref d) = components.db {
             gw = gw.with_store(Arc::clone(d));
             gw = gw.with_db_auth(Arc::clone(d));
+            if let Some(ref ss) = components.secrets_store {
+                gw = gw.with_secrets_store(Arc::clone(ss));
+            }
 
             // Bootstrap: create the first admin user from single-user config
             // so the owner appears in the Users admin panel immediately.