Add granular per-endpoint API key permissions

Replace the single all-or-nothing API key with a directory-based system
that supports multiple API keys with per-endpoint access control.

API keys are stored as TOML files in `<network_dir>/api_keys/`, each
specifying a hex key and a list of allowed endpoints (or "*" for admin).
The legacy `api_key` file is auto-migrated on first startup.

New RPC endpoints:
- `CreateApiKey`: generates a new key with specified permissions (admin only),
  writes it to disk, and updates the in-memory store
- `GetPermissions`: returns the allowed endpoints for the calling key
  (always accessible by any valid key)

The in-memory key store is shared via Arc<RwLock> across all connections
so keys created at runtime are immediately usable. File writes use
atomic rename for crash safety.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: benthecarman

e2e-tests/src/lib.rs

@@ -14,7 +14,6 @@ use std::process::{Child, Command, Stdio};
 use std::time::Duration;
 
 use corepc_node::Node;
-use hex_conservative::DisplayHex;
 use ldk_server_client::client::LdkServerClient;
 use ldk_server_client::ldk_server_protos::api::{GetNodeInfoRequest, GetNodeInfoResponse};
 use ldk_server_protos::api::{
@@ -176,17 +175,21 @@ client_trusts_lsp = true
 			}
 		});
 
-		// Wait for the api_key and tls.crt files to appear in the network subdir
+		// Wait for the api_keys/admin.toml and tls.crt files to appear
 		let network_dir = storage_dir.join("regtest");
-		let api_key_path = network_dir.join("api_key");
+		let admin_toml_path = network_dir.join("api_keys").join("admin.toml");
 		let tls_cert_path = storage_dir.join("tls.crt");
 
-		wait_for_file(&api_key_path, Duration::from_secs(30)).await;
+		wait_for_file(&admin_toml_path, Duration::from_secs(30)).await;
 		wait_for_file(&tls_cert_path, Duration::from_secs(30)).await;
 
-		// Read the API key (raw bytes -> hex)
-		let api_key_bytes = std::fs::read(&api_key_path).unwrap();
-		let api_key = api_key_bytes.to_lower_hex_string();
+		// Read the API key from admin.toml
+		let admin_toml_contents = std::fs::read_to_string(&admin_toml_path).unwrap();
+		let api_key = admin_toml_contents
+			.lines()
+			.find_map(|line| line.strip_prefix("key = \"")?.strip_suffix('"'))
+			.unwrap()
+			.to_string();
 
 		// Read TLS cert
 		let tls_cert_pem = std::fs::read(&tls_cert_path).unwrap();
@@ -311,6 +314,12 @@ pub fn run_cli(handle: &LdkServerHandle, args: &[&str]) -> serde_json::Value {
 		.unwrap_or_else(|e| panic!("Failed to parse CLI output as JSON: {e}\nOutput: {stdout}"))
 }
 
+/// Create a client with a specific API key.
+pub fn make_client(handle: &LdkServerHandle, api_key: &str) -> LdkServerClient {
+	let tls_cert_pem = std::fs::read(&handle.tls_cert_path).unwrap();
+	LdkServerClient::new(handle.base_url(), api_key.to_string(), &tls_cert_pem).unwrap()
+}
+
 /// Mine blocks and wait for all servers to sync to the new chain tip.
 pub async fn mine_and_sync(
 	bitcoind: &TestBitcoind, servers: &[&LdkServerHandle], block_count: u64,
@@ -428,6 +437,21 @@ pub async fn setup_funded_channel(
 	open_resp.user_channel_id
 }
 
+/// Create a restricted API key by calling the CreateApiKey RPC on the server.
+pub async fn create_restricted_client(
+	handle: &LdkServerHandle, name: &str, endpoints: Vec<String>,
+) -> LdkServerClient {
+	use ldk_server_client::ldk_server_protos::api::CreateApiKeyRequest;
+
+	let resp = handle
+		.client()
+		.create_api_key(CreateApiKeyRequest { name: name.to_string(), endpoints })
+		.await
+		.unwrap();
+
+	make_client(handle, &resp.api_key)
+}
+
 /// RabbitMQ event consumer for verifying events published by ldk-server.
 pub struct RabbitMqEventConsumer {
 	_connection: lapin::Connection,

e2e-tests/tests/e2e.rs

@@ -11,12 +11,14 @@ use std::str::FromStr;
 use std::time::Duration;
 
 use e2e_tests::{
-	find_available_port, mine_and_sync, run_cli, run_cli_raw, setup_funded_channel,
-	wait_for_onchain_balance, LdkServerHandle, RabbitMqEventConsumer, TestBitcoind,
+	create_restricted_client, find_available_port, make_client, mine_and_sync, run_cli,
+	run_cli_raw, setup_funded_channel, wait_for_onchain_balance, LdkServerHandle,
+	RabbitMqEventConsumer, TestBitcoind,
 };
 use ldk_node::lightning::ln::msgs::SocketAddress;
 use ldk_server_client::ldk_server_protos::api::{
-	Bolt11ReceiveRequest, Bolt12ReceiveRequest, OnchainReceiveRequest,
+	Bolt11ReceiveRequest, Bolt12ReceiveRequest, GetNodeInfoRequest, GetPermissionsRequest,
+	OnchainReceiveRequest,
 };
 use ldk_server_client::ldk_server_protos::types::{
 	bolt11_invoice_description, Bolt11InvoiceDescription,
@@ -611,3 +613,162 @@ async fn test_forwarded_payment_event() {
 
 	node_c.stop().unwrap();
 }
+
+#[tokio::test]
+async fn test_get_permissions_admin() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let resp = server.client().get_permissions(GetPermissionsRequest {}).await.unwrap();
+	assert!(
+		resp.endpoints.contains(&"*".to_string()),
+		"Expected admin key to have wildcard permission"
+	);
+}
+
+#[tokio::test]
+async fn test_create_api_key_and_get_permissions() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let restricted_client = create_restricted_client(
+		&server,
+		"read-only",
+		vec!["GetNodeInfo".to_string(), "GetBalances".to_string()],
+	)
+	.await;
+
+	let resp = restricted_client.get_permissions(GetPermissionsRequest {}).await.unwrap();
+	assert_eq!(resp.endpoints, vec!["GetBalances", "GetNodeInfo"]);
+}
+
+#[tokio::test]
+async fn test_restricted_key_allowed_endpoint() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let restricted_client =
+		create_restricted_client(&server, "node-info-only", vec!["GetNodeInfo".to_string()]).await;
+
+	let resp = restricted_client.get_node_info(GetNodeInfoRequest {}).await;
+	assert!(resp.is_ok(), "Restricted key should be able to call allowed endpoint");
+	assert_eq!(resp.unwrap().node_id, server.node_id());
+}
+
+#[tokio::test]
+async fn test_restricted_key_denied_endpoint() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let restricted_client =
+		create_restricted_client(&server, "info-only", vec!["GetNodeInfo".to_string()]).await;
+
+	let resp = restricted_client.onchain_receive(OnchainReceiveRequest {}).await;
+	assert!(resp.is_err(), "Restricted key should be denied access to unauthorized endpoint");
+}
+
+#[tokio::test]
+async fn test_restricted_key_get_permissions_always_allowed() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	// Create key with no endpoints at all (except GetPermissions which is always allowed)
+	let restricted_client =
+		create_restricted_client(&server, "perms-only", vec!["GetNodeInfo".to_string()]).await;
+
+	let resp = restricted_client.get_permissions(GetPermissionsRequest {}).await;
+	assert!(resp.is_ok(), "GetPermissions should always be allowed");
+}
+
+#[tokio::test]
+async fn test_create_api_key_via_cli() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let output =
+		run_cli(&server, &["create-api-key", "cli-test-key", "-e", "GetNodeInfo", "GetBalances"]);
+	let api_key = output["api_key"].as_str().unwrap();
+	assert_eq!(api_key.len(), 64);
+	assert!(api_key.chars().all(|c| c.is_ascii_hexdigit()));
+}
+
+#[tokio::test]
+async fn test_invalid_api_key_rejected() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let bad_key = "ff".repeat(32);
+	let bad_client = make_client(&server, &bad_key);
+
+	let resp = bad_client.get_node_info(GetNodeInfoRequest {}).await;
+	assert!(resp.is_err(), "Invalid API key should be rejected");
+}
+
+#[tokio::test]
+async fn test_restricted_key_cannot_create_api_key() {
+	use ldk_server_client::ldk_server_protos::api::CreateApiKeyRequest;
+
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let restricted = create_restricted_client(&server, "limited", vec!["GetNodeInfo".to_string()])
+		.await;
+
+	// Restricted key should not be able to create new keys
+	let result = restricted
+		.create_api_key(CreateApiKeyRequest {
+			name: "sneaky".to_string(),
+			endpoints: vec!["*".to_string()],
+		})
+		.await;
+	assert!(result.is_err(), "Restricted key should not be able to create API keys");
+	assert_eq!(
+		result.unwrap_err().error_code,
+		ldk_server_client::error::LdkServerErrorCode::AuthError
+	);
+}
+
+#[tokio::test]
+async fn test_create_api_key_duplicate_name_rejected() {
+	use ldk_server_client::ldk_server_protos::api::CreateApiKeyRequest;
+
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	// First creation should succeed
+	let result = server
+		.client()
+		.create_api_key(CreateApiKeyRequest {
+			name: "my-key".to_string(),
+			endpoints: vec!["GetNodeInfo".to_string()],
+		})
+		.await;
+	assert!(result.is_ok());
+
+	// Duplicate name should fail
+	let result = server
+		.client()
+		.create_api_key(CreateApiKeyRequest {
+			name: "my-key".to_string(),
+			endpoints: vec!["GetNodeInfo".to_string()],
+		})
+		.await;
+	assert!(result.is_err(), "Duplicate API key name should be rejected");
+}
+
+#[tokio::test]
+async fn test_create_api_key_invalid_endpoint_rejected() {
+	use ldk_server_client::ldk_server_protos::api::CreateApiKeyRequest;
+
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	let result = server
+		.client()
+		.create_api_key(CreateApiKeyRequest {
+			name: "bad-key".to_string(),
+			endpoints: vec!["NonExistentEndpoint".to_string()],
+		})
+		.await;
+	assert!(result.is_err(), "Unknown endpoint should be rejected");
+}

ldk-server-cli/src/config.rs

@@ -13,7 +13,6 @@ use serde::{Deserialize, Serialize};
 
 const DEFAULT_CONFIG_FILE: &str = "config.toml";
 const DEFAULT_CERT_FILE: &str = "tls.crt";
-const API_KEY_FILE: &str = "api_key";
 
 pub fn get_default_data_dir() -> Option<PathBuf> {
 	#[cfg(target_os = "macos")]
@@ -40,8 +39,12 @@ pub fn get_default_cert_path() -> Option<PathBuf> {
 	get_default_data_dir().map(|path| path.join(DEFAULT_CERT_FILE))
 }
 
-pub fn get_default_api_key_path(network: &str) -> Option<PathBuf> {
-	get_default_data_dir().map(|path| path.join(network).join(API_KEY_FILE))
+/// Reads the admin API key from `api_keys/admin.toml` in the network directory.
+pub fn get_default_admin_api_key(network: &str) -> Option<String> {
+	let admin_toml_path = get_default_data_dir()?.join(network).join("api_keys").join("admin.toml");
+	let contents = std::fs::read_to_string(&admin_toml_path).ok()?;
+	let parsed: toml::Value = toml::from_str(&contents).ok()?;
+	parsed.get("key").and_then(|v| v.as_str()).map(String::from)
 }
 
 #[derive(Debug, Deserialize)]

ldk-server-cli/src/main.rs

@@ -12,7 +12,7 @@ use std::path::PathBuf;
 use clap::{CommandFactory, Parser, Subcommand};
 use clap_complete::{generate, Shell};
 use config::{
-	get_default_api_key_path, get_default_cert_path, get_default_config_path, load_config,
+	get_default_admin_api_key, get_default_cert_path, get_default_config_path, load_config,
 };
 use hex_conservative::DisplayHex;
 use ldk_server_client::client::LdkServerClient;
@@ -24,12 +24,13 @@ use ldk_server_client::ldk_server_protos::api::{
 	Bolt11ReceiveRequest, Bolt11ReceiveResponse, Bolt11SendRequest, Bolt11SendResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
 	CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse,
-	DisconnectPeerRequest, DisconnectPeerResponse, ExportPathfindingScoresRequest,
-	ForceCloseChannelRequest, ForceCloseChannelResponse, GetBalancesRequest, GetBalancesResponse,
-	GetNodeInfoRequest, GetNodeInfoResponse, GetPaymentDetailsRequest, GetPaymentDetailsResponse,
-	GraphGetChannelRequest, GraphGetChannelResponse, GraphGetNodeRequest, GraphGetNodeResponse,
-	GraphListChannelsRequest, GraphListChannelsResponse, GraphListNodesRequest,
-	GraphListNodesResponse, ListChannelsRequest, ListChannelsResponse,
+	CreateApiKeyRequest, CreateApiKeyResponse, DisconnectPeerRequest, DisconnectPeerResponse,
+	ExportPathfindingScoresRequest, ForceCloseChannelRequest, ForceCloseChannelResponse,
+	GetBalancesRequest, GetBalancesResponse, GetNodeInfoRequest, GetNodeInfoResponse,
+	GetPaymentDetailsRequest, GetPaymentDetailsResponse, GetPermissionsRequest,
+	GetPermissionsResponse, GraphGetChannelRequest, GraphGetChannelResponse, GraphGetNodeRequest,
+	GraphGetNodeResponse, GraphListChannelsRequest, GraphListChannelsResponse,
+	GraphListNodesRequest, GraphListNodesResponse, ListChannelsRequest, ListChannelsResponse,
 	ListForwardedPaymentsRequest, ListPaymentsRequest, OnchainReceiveRequest,
 	OnchainReceiveResponse, OnchainSendRequest, OnchainSendResponse, OpenChannelRequest,
 	OpenChannelResponse, SignMessageRequest, SignMessageResponse, SpliceInRequest,
@@ -411,6 +412,20 @@ enum Commands {
 		#[arg(help = "The hex-encoded node ID to look up")]
 		node_id: String,
 	},
+	#[command(about = "Create a new API key with specific endpoint permissions (admin-only)")]
+	CreateApiKey {
+		#[arg(help = "A human-readable name for the API key")]
+		name: String,
+		#[arg(
+			short,
+			long,
+			num_args = 1..,
+			help = "List of endpoint names this key is permitted to access"
+		)]
+		endpoints: Vec<String>,
+	},
+	#[command(about = "Retrieve the permissions of the current API key")]
+	GetPermissions,
 	#[command(about = "Generate shell completions for the CLI")]
 	Completions {
 		#[arg(
@@ -434,18 +449,16 @@ async fn main() {
 	let config_path = cli.config.map(PathBuf::from).or_else(get_default_config_path);
 	let config = config_path.as_ref().and_then(|p| load_config(p).ok());
 
-	// Get API key from argument, then from api_key file
+	// Get API key from argument, then from admin.toml
 	let api_key = cli
 		.api_key
 		.or_else(|| {
-			// Try to read from api_key file based on network (file contains raw bytes)
-			let network = config.as_ref().and_then(|c| c.network().ok()).unwrap_or("bitcoin".to_string());
-			get_default_api_key_path(&network)
-				.and_then(|path| std::fs::read(&path).ok())
-				.map(|bytes| bytes.to_lower_hex_string())
+			let network =
+				config.as_ref().and_then(|c| c.network().ok()).unwrap_or("bitcoin".to_string());
+			get_default_admin_api_key(&network)
 		})
 		.unwrap_or_else(|| {
-			eprintln!("API key not provided. Use --api-key or ensure the api_key file exists at ~/.ldk-server/[network]/api_key");
+			eprintln!("API key not provided. Use --api-key or ensure api_keys/admin.toml exists at ~/.ldk-server/[network]/api_keys/admin.toml");
 			std::process::exit(1);
 		});
 
@@ -844,6 +857,16 @@ async fn main() {
 				client.graph_get_node(GraphGetNodeRequest { node_id }).await,
 			);
 		},
+		Commands::CreateApiKey { name, endpoints } => {
+			handle_response_result::<_, CreateApiKeyResponse>(
+				client.create_api_key(CreateApiKeyRequest { name, endpoints }).await,
+			);
+		},
+		Commands::GetPermissions => {
+			handle_response_result::<_, GetPermissionsResponse>(
+				client.get_permissions(GetPermissionsRequest {}).await,
+			);
+		},
 		Commands::Completions { .. } => unreachable!("Handled above"),
 	}
 }