Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat: add authenticated self-service native API keys

Vinicius Miguel3c501ab55bf7
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b8055aa5..1efb9338 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -45,6 +45,19 @@ jobs:
- uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
- run: cargo clippy --workspace --all-targets -- -D warnings
+ self-service-keys:
+ name: optional self-service-keys
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ - uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable
+ with:
+ components: clippy
+ - uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2
+ - run: cargo clippy --workspace --all-targets --features ai-memory-cli/self-service-keys -- -D warnings
+ - run: cargo test -p ai-memory-mcp --features self-service-keys self_service_keys
+ - run: cargo test -p ai-memory-cli --features self-service-keys --lib self_service_keys
+
test:
name: test (${{ matrix.os }})
strategy:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a2f8424..5f285b39 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,11 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Added
+- Added optional human-session self-service native API keys, gated by the
+ `self-service-keys` build feature and runtime switch. Reused existing
+ authentication, credential hashing, and SQLite storage. (#1231)
+
## [3.0.0] - 2026-10-13
### Added
diff --git a/README.md b/README.md
index 65c4a6f4..8d254b5d 100644
--- a/README.md
+++ b/README.md
@@ -674,3 +674,6 @@ MIT. See [LICENSE](LICENSE).
This codebase is being built collaboratively with Claude Code
(Anthropic Claude Opus 4.7) following the plan documented in
`docs/design-decisions.md`.
+
+Optional [self-service MCP API keys](docs/self-service-keys.md) reuse existing
+browser authentication and are disabled by default.
diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.toml
index 0261aa99..37c020ac 100644
--- a/crates/ai-memory-cli/Cargo.toml
+++ b/crates/ai-memory-cli/Cargo.toml
@@ -23,6 +23,10 @@ path = "src/main.rs"
# a second ~120 MB harness binary for it that contains no tests.
test = false
+[features]
+default = []
+self-service-keys = ["ai-memory-mcp/self-service-keys"]
+
[dependencies]
ai-memory-consolidate.workspace = true
ai-memory-core.workspace = true
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 2834f73a..72661b26 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -3336,6 +3336,11 @@ pub enum TransportKind {
/// Arguments for `serve`.
#[derive(Debug, Args)]
pub struct ServeArgs {
+ /// Enable optional browser-session management API (requires an opt-in build).
+ #[cfg(feature = "self-service-keys")]
+ #[arg(long, env = "AI_MEMORY_ENABLE_SELF_SERVICE_KEYS")]
+ pub enable_self_service_keys: bool,
+
/// Transport to expose the MCP server on.
#[arg(long, value_enum, default_value_t = TransportKind::Stdio)]
pub transport: TransportKind,
@@ -3468,6 +3473,33 @@ pub struct WritePageArgs {
#[cfg(test)]
mod tests {
+ #[cfg(feature = "self-service-keys")]
+ #[test]
+ fn self_service_keys_is_runtime_opt_in() {
+ let parsed = Cli::try_parse_from(["ai-memory", "serve"]).unwrap();
+ let Command::Serve(args) = parsed.command else {
+ panic!("serve")
+ };
+ assert!(!args.enable_self_service_keys);
+ let parsed = Cli::try_parse_from([
+ "ai-memory",
+ "serve",
+ "--transport",
+ "http",
+ "--enable-self-service-keys",
+ ])
+ .unwrap();
+ let Command::Serve(args) = parsed.command else {
+ panic!("serve")
+ };
+ assert!(args.enable_self_service_keys);
+ }
+ #[cfg(not(feature = "self-service-keys"))]
+ #[test]
+ fn self_service_keys_flag_is_absent_by_default() {
+ assert!(Cli::try_parse_from(["ai-memory", "serve", "--enable-self-service-keys"]).is_err());
+ }
+
use super::*;
use clap::{CommandFactory, Parser};
use std::collections::BTreeSet;
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 4dba5368..1ca18ba7 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -1151,6 +1151,10 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
validate_web_ui_args(args.enable_web, args.web_ui_dir.as_deref())?;
refuse_a_missing_token_file(&config.auth)?;
+ #[cfg(feature = "self-service-keys")]
+ if args.enable_self_service_keys && !matches!(args.transport, TransportKind::Http) {
+ anyhow::bail!("--enable-self-service-keys requires --transport http");
+ }
config.require_llm_fallback_credentials()?;
// Merge config + CLI CORS origins (config first, CLI adds new entries).
@@ -1834,6 +1838,24 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
auth_state.clone(),
expire_legacy_cookie_mw,
)));
+ #[cfg(feature = "self-service-keys")]
+ let router = if args.enable_self_service_keys {
+ router.merge(ai_memory_mcp::self_service_keys::router(
+ ai_memory_mcp::self_service_keys::SelfServiceKeysState {
+ reader: store.reader.clone(),
+ writer: store.writer.clone(),
+ pepper: config
+ .auth
+ .token_pepper
+ .clone()
+ .filter(|p| !p.trim().is_empty())
+ .map(TokenPepper::new),
+ },
+ auth_state.clone(),
+ ))
+ } else {
+ router
+ };
let router = apply_host_layer(router, config.allowed_hosts.clone());
// Host the entire surface under the configured base path. Empty
// base = root (unchanged). The auth/host layers are already
diff --git a/crates/ai-memory-mcp/Cargo.toml b/crates/ai-memory-mcp/Cargo.toml
index 5ad36d8f..aaccd21c 100644
--- a/crates/ai-memory-mcp/Cargo.toml
+++ b/crates/ai-memory-mcp/Cargo.toml
@@ -12,6 +12,10 @@ description = "MCP server transport and tool router for ai-memory."
# statically links the whole dep graph and gets scanned by macOS on
# first run.
+[features]
+default = []
+self-service-keys = []
+
[dependencies]
ai-memory-core.workspace = true
ai-memory-consolidate.workspace = true
diff --git a/crates/ai-memory-mcp/src/lib.rs b/crates/ai-memory-mcp/src/lib.rs
index 7a4c3295..54e87947 100644
--- a/crates/ai-memory-mcp/src/lib.rs
+++ b/crates/ai-memory-mcp/src/lib.rs
@@ -38,3 +38,6 @@ extern crate self as ai_memory_mcp;
#[cfg(test)]
#[path = "../tests/suite/mod.rs"]
mod integration;
+
+#[cfg(feature = "self-service-keys")]
+pub mod self_service_keys;
diff --git a/crates/ai-memory-mcp/src/self_service_keys.rs b/crates/ai-memory-mcp/src/self_service_keys.rs
new file mode 100644
index 00000000..baf16483
--- /dev/null
+++ b/crates/ai-memory-mcp/src/self_service_keys.rs
@@ -0,0 +1,137 @@
+//! Personal native API keys through existing browser-session authentication.
+use crate::{auth::AuthState, human_auth::require_session};
+use ai_memory_core::{ApiCredentialId, UserId};
+use ai_memory_store::{ReaderPool, StoreError, TokenPepper, WriterHandle};
+use axum::{
+ Extension, Json, Router,
+ extract::{Path, State},
+ http::{Request, StatusCode, header},
+ middleware::{self, Next},
+ response::{IntoResponse, Response},
+ routing::{get, post},
+};
+use serde::Deserialize;
+use serde_json::{Value, json};
+use std::sync::Arc;
+/// Dependencies resolved once at startup; credentials never read server config.
+#[derive(Clone)]
+pub struct SelfServiceKeysState {
+ /// Read pool for credential ownership.
+ pub reader: ReaderPool,
+ /// Existing single writer.
+ pub writer: WriterHandle,
+ /// Server-configured native-key pepper.
+ pub pepper: Option<TokenPepper>,
+}
+/// Human sessions only. Machine bearers and pending password changes are refused.
+pub fn router(state: SelfServiceKeysState, auth: Arc<AuthState>) -> Router {
+ Router::new()
+ .route(
+ "/management/v1/credentials",
+ get(credentials).post(create_credential),
+ )
+ .route(
+ "/management/v1/credentials/{id}/revoke",
+ post(revoke_credential),
+ )
+ .with_state(Arc::new(state))
+ .layer(middleware::from_fn(ready))
+ .layer(middleware::from_fn_with_state(auth, require_session))
+ .layer(middleware::from_fn(no_store))
+}
+async fn no_store(req: Request<axum::body::Body>, next: Next) -> Response {
+ let mut response = next.run(req).await;
+ response.headers_mut().insert(
+ header::CACHE_CONTROL,
+ axum::http::HeaderValue::from_static("private, no-store"),
+ );
+ response
+}
+
+async fn ready(
+ Extension(live): Extension<ai_memory_store::LiveWebSession>,
+ req: Request<axum::body::Body>,
+ next: Next,
+) -> Response {
+ if live.user.must_change_password {
+ return error(StatusCode::FORBIDDEN, "password change required");
+ }
+ next.run(req).await
+}
+
+fn error(status: StatusCode, message: &str) -> Response {
+ (status, Json(json!({"error": message}))).into_response()
+}
+
+fn store_error(e: StoreError) -> Response {
+ match e {
+ StoreError::NotFound(_) => error(StatusCode::NOT_FOUND, "not found"),
+ StoreError::Forbidden(message) => error(StatusCode::FORBIDDEN, message),
+ StoreError::InvalidState(message) => error(StatusCode::CONFLICT, &message),
+ other => {
+ tracing::warn!(error = %other, "management store operation failed");
+ error(
+ StatusCode::INTERNAL_SERVER_ERROR,
+ "management operation failed",
+ )
+ }
+ }
+}
+
+async fn credentials(
+ State(state): State<Arc<SelfServiceKeysState>>,
+ Extension(user): Extension<UserId>,
+) -> Result<Json<Value>, Response> {
+ Ok(Json(
+ json!({"credentials": state.reader.list_api_credentials_for_user(user).await.map_err(store_error)?}),
+ ))
+}
+
+#[derive(Deserialize)]
+struct KeyBody {
+ label: String,
+}
+
+async fn create_credential(
+ State(state): State<Arc<SelfServiceKeysState>>,
+ Extension(user): Extension<UserId>,
+ Json(body): Json<KeyBody>,
+) -> Result<Json<Value>, Response> {
+ let pepper = state
+ .pepper
+ .as_ref()
+ .ok_or_else(|| error(StatusCode::CONFLICT, "API keys are not configured"))?;
+ let token = ai_memory_store::generate_api_key().map_err(store_error)?;
+ let id = state
+ .writer
+ .create_api_credential(
+ ApiCredentialId::new(),
+ user,
+ body.label,
+ ai_memory_store::hash_token(&token, pepper),
+ Some(ai_memory_store::api_key_preview(&token)),
+ )
+ .await
+ .map_err(store_error)?;
+ Ok(Json(json!({"id": id, "token": token})))
+}
+
+async fn revoke_credential(
+ State(state): State<Arc<SelfServiceKeysState>>,
+ Extension(user): Extension<UserId>,
+ Path(id): Path<ApiCredentialId>,
+) -> Result<Json<Value>, Response> {
+ let key = state
+ .reader
+ .find_api_credential(id)
+ .await
+ .map_err(store_error)?
+ .filter(|key| key.user_id == user)
+ .ok_or_else(|| error(StatusCode::NOT_FOUND, "credential not found"))?;
+ state
+ .writer
+ .revoke_api_credential(key.id)
+ .await
+ .map_err(store_error)?;
+ Ok(Json(json!({"revoked": true})))
+}
diff --git a/crates/ai-memory-mcp/tests/suite/mod.rs b/crates/ai-memory-mcp/tests/suite/mod.rs
index 1c8fb5c4..aac13724 100644
--- a/crates/ai-memory-mcp/tests/suite/mod.rs
+++ b/crates/ai-memory-mcp/tests/suite/mod.rs
@@ -40,3 +40,6 @@ mod retrieval_via_tools;
mod slot_identity;
mod stress_autoscope;
mod web_search_parity;
+
+#[cfg(feature = "self-service-keys")]
+mod self_service_keys;
diff --git a/crates/ai-memory-mcp/tests/suite/self_service_keys.rs b/crates/ai-memory-mcp/tests/suite/self_service_keys.rs
new file mode 100644
index 00000000..5b8a73b9
--- /dev/null
+++ b/crates/ai-memory-mcp/tests/suite/self_service_keys.rs
@@ -0,0 +1,282 @@
+//! Adversarial management tests exercise real cookie/CSRF and writer isolation.
+use ai_memory_core::{NewUser, UserId, UserRole};
+use ai_memory_mcp::{
+ HumanAuthRuntime,
+ auth::AuthState,
+ human_auth::LoginLimiter,
+ self_service_keys::{SelfServiceKeysState as ManagementState, router},
+};
+use ai_memory_store::{Store, TokenPepper, hash_session_secret};
+use axum::{
+ Router,
+ body::Body,
+ http::{Request, StatusCode},
+};
+use serde_json::{Value, json};
+use std::sync::Arc;
+use tempfile::TempDir;
+use tower::ServiceExt;
+
+struct Browser {
+ cookie: String,
+ csrf: String,
+ user: UserId,
+}
+struct Harness {
+ _tmp: TempDir,
+ store: Store,
+ router: Router,
+ alice: Browser,
+ bob: Browser,
+ root: Browser,
+}
+
+async fn browser(store: &Store, name: &str, role: UserRole, must_change: bool) -> Browser {
+ let phc = ai_memory_store::password::hash_password("password-for-test".into())
+ .await
+ .unwrap();
+ let user = store
+ .writer
+ .create_human_user(
+ NewUser {
+ username: name.into(),
+ name: None,
+ email: None,
+ },
+ role,
+ Some(phc.clone()),
+ must_change,
+ )
+ .await
+ .unwrap();
+ let secret = ai_memory_store::web_sessions::generate_session_secret().unwrap();
+ let csrf = ai_memory_store::web_sessions::generate_csrf_secret().unwrap();
+ store
+ .writer
+ .issue_web_session(
+ user,
+ phc,
+ role,
+ must_change,
+ hash_session_secret(&secret),
+ hash_session_secret(&csrf),
+ )
+ .await
+ .unwrap();
+ Browser {
+ user,
+ cookie: format!("ai_memory_session={secret}; ai_memory_csrf={csrf}"),
+ csrf,
+ }
+}
+async fn harness() -> Harness {
+ let tmp = TempDir::new().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let alice = browser(&store, "alice", UserRole::User, false).await;
+ let bob = browser(&store, "bob", UserRole::User, false).await;
+ let root = browser(&store, "root", UserRole::Root, false).await;
+ let auth = Arc::new(
+ AuthState::new(Some("root-bearer".into())).with_human(HumanAuthRuntime {
+ reader: store.reader.clone(),
+ writer: store.writer.clone(),
+ recovery_token_hash: None,
+ root_username: "root".into(),
+ root_name: None,
+ root_email: None,
+ reserved_passwords: vec![],
+ trusted_proxy_cidrs: vec![],
+ limiter: Arc::new(LoginLimiter::default()),
+ }),
+ );
+ let router = router(
+ ManagementState {
+ reader: store.reader.clone(),
+ writer: store.writer.clone(),
+ pepper: Some(TokenPepper::new("test-pepper")),
+ },
+ auth,
+ );
+ Harness {
+ _tmp: tmp,
+ store,
+ router,
+ alice,
+ bob,
+ root,
+ }
+}
+async fn call(
+ h: &Harness,
+ browser: Option<&Browser>,
+ method: &str,
+ uri: &str,
+ body: Value,
+ csrf: bool,
+) -> (StatusCode, Value) {
+ let mut request = Request::builder()
+ .method(method)
+ .uri(uri)
+ .header("content-type", "application/json");
+ if let Some(browser) = browser {
+ request = request.header("cookie", &browser.cookie);
+ if csrf {
+ request = request.header("x-csrf-token", &browser.csrf);
+ }
+ }
+ let response = h
+ .router
+ .clone()
+ .oneshot(request.body(Body::from(body.to_string())).unwrap())
+ .await
+ .unwrap();
+ assert_eq!(response.headers()["cache-control"], "private, no-store");
+ let status = response.status();
+ let bytes = axum::body::to_bytes(response.into_body(), 1_000_000)
+ .await
+ .unwrap();
+ (
+ status,
+ serde_json::from_slice(&bytes).unwrap_or(Value::Null),
+ )
+}
+
+#[tokio::test]
+async fn self_service_keys_refuse_foreign_ids_csrf_machine_and_pending_password_with_owner_controls()
+ {
+ let h = harness().await;
+ let path = "/management/v1/credentials";
+ assert_eq!(
+ call(&h, None, "GET", path, Value::Null, false).await.0,
+ StatusCode::UNAUTHORIZED
+ );
+ let response = h
+ .router
+ .clone()
+ .oneshot(
+ Request::builder()
+ .uri(path)
+ .header("authorization", "Bearer root-bearer")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+ assert_eq!(
+ call(
+ &h,
+ Some(&h.alice),
+ "POST",
+ path,
+ json!({"label":"missing-csrf"}),
+ false
+ )
+ .await
+ .0,
+ StatusCode::FORBIDDEN
+ );
+ let pending = browser(&h.store, "pending", UserRole::User, true).await;
+ assert_eq!(
+ call(
+ &h,
+ Some(&pending),
+ "POST",
+ path,
+ json!({"label":"refused"}),
+ true
+ )
+ .await
+ .0,
+ StatusCode::FORBIDDEN
+ );
+ let issued = call(
+ &h,
+ Some(&h.alice),
+ "POST",
+ path,
+ json!({"label":"own key","username":"bob"}),
+ true,
+ )
+ .await;
+ assert_eq!(issued.0, StatusCode::OK);
+ assert!(issued.1["token"].as_str().unwrap().starts_with("aim_"));
+ let credentials = h
+ .store
+ .reader
+ .list_api_credentials_for_user(h.alice.user)
+ .await
+ .unwrap();
+ assert_eq!(credentials.len(), 1);
+ assert_eq!(credentials[0].user_id, h.alice.user);
+ assert!(
+ h.store
+ .reader
+ .list_api_credentials_for_user(h.bob.user)
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ let revoke = format!(
+ "/management/v1/credentials/{}/revoke",
+ issued.1["id"].as_str().unwrap()
+ );
+ assert_eq!(
+ call(&h, Some(&h.bob), "POST", &revoke, json!({}), true)
+ .await
+ .0,
+ StatusCode::NOT_FOUND
+ );
+ assert_eq!(
+ call(&h, Some(&h.alice), "POST", &revoke, json!({}), false)
+ .await
+ .0,
+ StatusCode::FORBIDDEN
+ );
+ assert!(
+ h.store
+ .reader
+ .list_api_credentials_for_user(h.alice.user)
+ .await
+ .unwrap()[0]
+ .revoked_at
+ .is_none()
+ );
+ assert_eq!(
+ call(&h, Some(&h.alice), "POST", &revoke, json!({}), true)
+ .await
+ .0,
+ StatusCode::OK
+ );
+ assert!(
+ h.store
+ .reader
+ .list_api_credentials_for_user(h.alice.user)
+ .await
+ .unwrap()[0]
+ .revoked_at
+ .is_some()
+ );
+ // A root browser also issues only a key owned by its immutable user id.
+ assert_eq!(
+ call(
+ &h,
+ Some(&h.root),
+ "POST",
+ path,
+ json!({"label":"root's machine key"}),
+ true
+ )
+ .await
+ .0,
+ StatusCode::OK
+ );
+ assert_eq!(
+ h.store
+ .reader
+ .list_api_credentials_for_user(h.root.user)
+ .await
+ .unwrap()
+ .len(),
+ 1
+ );
+}
diff --git a/docs/security-boundaries.md b/docs/security-boundaries.md
index 074bc464..5d15de5b 100644
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@ -110,6 +110,8 @@ means the boundary is not built yet.
| 16 | Relay queue identity, migration, and private filesystem state | `companions/ai-memory-relay/src/queue.rs` `Queue::open_inner` performs read-only identity preflight, rechecks under `IMMEDIATE`, commits schema and metadata together; `configure` checks the presence of user objects and rechecks `identity`/`schema_version` metadata on the same connection before every bounded BUSY/LOCKED retry; `fsguard.rs` checks existing paths and creates owner-only files before SQLite opens them | `tests/relay.rs` `a_foreign_database_is_refused_byte_for_byte`, `unknown_schemas_refuse_without_mutation`, `a_foreign_database_with_a_writer_is_refused_before_write_coordination`, `a_foreign_identity_after_preflight_is_refused_without_mutation`, `a_foreign_identity_during_journal_retry_is_refused_without_mutation`, `journal_retry_refuses_a_changed_version_or_empty_database_without_mutation`; controls: `journal_transition_retries_sqlite_lock_without_losing_v1_values`, `fresh_queue_init_and_v1_reopens_work_across_processes`; recovery: `interrupted_and_failed_migrations_roll_back_and_recover`, `journal_reclassification_busy_preserves_committed_migration_and_retries_same_queue`; diagnostics: `classification_read_failures_display_the_sqlite_cause_once_and_preserve_foreign_bytes`; Unix privacy: `the_queue_database_and_its_sidecars_are_owner_only` and the contended migration control | Guard-removal proof covers preflight, locked recheck, and journal retry identity/version checks; full table structure is outside this classification. Windows path rejection is preserved; Windows ACL hardening remains operator-owned |
+| 18 | Human-session self-service native API keys | `mcp/src/self_service_keys.rs`: human session/CSRF and completed password change; creation takes authenticated `UserId`, never a supplied username; revocation verifies immutable owner; existing native keys remain User-level. | `self_service_keys_refuse_foreign_ids_csrf_machine_and_pending_password_with_owner_controls` (anonymous/machine/CSRF/pending-password/foreign-id refusal, supplied username ignored, legitimate User/Root controls). | Adversarial controls and guard-removal proofs. |
+
## Keeping this current (the standing protocol)
1. **Touch a guard, add/extend its adversarial test.** Any change to code in the
diff --git a/docs/self-service-keys.md b/docs/self-service-keys.md
new file mode 100644
index 00000000..de82e202
--- /dev/null
+++ b/docs/self-service-keys.md
@@ -0,0 +1,22 @@
+# Self-service MCP API keys
+
+Build with `--features self-service-keys` and start the HTTP server with
+`--enable-self-service-keys` (`AI_MEMORY_ENABLE_SELF_SERVICE_KEYS=true`). Both
+switches default to off. Existing human browser sessions may GET or POST
+`/management/v1/credentials` and POST `/management/v1/credentials/{id}/revoke`.
+Machine bearers and password-change-required sessions cannot use these routes;
+mutations require the existing CSRF cookie/header pair.
+
+POST a `label` to create a key for the authenticated immutable user id. The
+server returns the `aim_` key once and stores only its peppered hash. Configure
+`[auth] token_pepper` as for the existing native-key administration commands.
+Revocation refuses another user's credential id. Listing returns metadata and
+previews, never token material. Responses use `Cache-Control: private, no-store`.
+
+Use the key as an Authorization: Bearer credential for `/mcp` and lifecycle
+hooks. It remains User-level even when its owner is an Admin. Disabling browser
+access does not revoke machine keys; revoke them separately. No identity
+provider, password implementation, database, or schema is added.
+
+Run `cargo t -p ai-memory-mcp --features self-service-keys` for the adversarial
+anonymous, machine, CSRF, pending-password, foreign-id, and legitimate owner tests.
diff --git a/docs/users.md b/docs/users.md
index a5b582c8..2e3cb1fc 100644
--- a/docs/users.md
+++ b/docs/users.md
@@ -803,3 +803,5 @@ ones who should keep access; nothing is granted automatically.
authenticates as, like any other. The Keycloak/OIDC `sid` claim is also not an ai-memory agent
session id; session auto-scope needs the lifecycle-hook session id or explicit
`workspace` + `project` / `scopes`.
+
+See [Self-service MCP API keys](self-service-keys.md) for the opt-in HTTP surface.