# How to Handle Endpoint Identity with SecretKey in iroh

> Learn how to handle endpoint identity with SecretKey in iroh. Supply a SecretKey via the builder for a stable, persistent identity across restarts. Get started with iroh today.

- Repository: [number zero/iroh](https://github.com/n0-computer/iroh)
- Tags: how-to-guide
- Published: 2026-07-16

---

**In iroh, an endpoint's identity is derived from a cryptographic `SecretKey`, which you can supply via the builder to create a stable, persistent identity across restarts.**

The iroh networking library (n0-computer/iroh) uses cryptographic keys to establish peer identity. Each endpoint is identified by a `SecretKey`, and the public portion of this key becomes the `EndpointId` that other peers use to address you. Understanding how to manage this key is essential for building persistent, recognizable nodes in a distributed system.

## Understanding Endpoint Identity Architecture

### SecretKey Storage and Resolution

The `Endpoint` builder maintains an optional `secret_key: Option<SecretKey>` field that stores your identity configuration before binding. According to the source code in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs), this field is defined at line 525. When you call `Builder::bind()`, the library resolves this key at lines 226–227, generating a fresh random key if you have not supplied one.

The secret key is ultimately stored inside the TLS configuration structure. In [`iroh/src/tls.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/tls.rs) at lines 46–48, the `tls_config` struct holds the `secret_key` that will be used for all cryptographic handshakes.

### Identity Generation Flow

If you do not provide a custom key, iroh generates a random 32-byte key automatically. This occurs during the bind process in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs) (lines 224–236). While convenient for temporary connections, auto-generated keys result in a new `EndpointId` on every restart, requiring peers to rediscover your address.

## Supplying a Custom Secret Key

### The Builder Method

To maintain a consistent identity, call the `secret_key` method on the builder before invoking `bind`. The method signature in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs) (lines 524–527) is:

```rust
pub fn secret_key(mut self, secret_key: SecretKey) -> Self

```

This method consumes the builder and returns it with the identity configured, allowing chain construction.

### Practical Implementation

Supply your own key to ensure peers can reconnect to you after a restart:

```rust
use iroh::{Endpoint, endpoint::presets};
use iroh_base::SecretKey;

// Load or create a secret key (e.g. from a file, env var, etc.)
let my_key = SecretKey::from_bytes(&[0x01; 32]); // replace with real key material

let endpoint = Endpoint::builder(presets::N0)
    .secret_key(my_key)           // set the identity
    .bind()
    .await?;

```

When you provide a custom key, the resulting `EndpointId` remains stable across application restarts, enabling long-term peer relationships.

## Retrieving Identity Information

### Accessing the SecretKey

After binding, you can retrieve the secret key reference using the accessor defined at lines 1172–1174 in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs):

```rust
pub fn secret_key(&self) -> &SecretKey

```

This returns a reference to the stored key, which is useful for serialization or verification purposes.

### Getting the Public EndpointId

To obtain the public identifier that peers use to reach your endpoint, use the `id` method. According to lines 1180–1182 in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs), the signature is:

```rust
pub fn id(&self) -> EndpointId

```

This method derives the public key from the secret material and returns the `EndpointId` suitable for sharing with other nodes.

## Security Best Practices

### Key Confidentiality

The **secret key must remain secret** at all times. Possession of this key allows complete impersonation of your endpoint. Store it in secure hardware or encrypted storage, and never transmit it over unsecured channels.

### Debugging with Key Logging

For development and debugging, iroh supports TLS key logging via `Builder::keylog(true)`. This feature is implemented in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs) at lines 324–332. **Never enable this in production**, as it writes sensitive key material to disk, compromising the security of all connections.

### Entropy Requirements

When generating custom keys, ensure the source provides at least 32 bytes of cryptographically secure random data. Weak or predictable keys expose your endpoint to brute-force attacks and identity theft.

## Summary

- **Supply a `SecretKey`** via `Builder::secret_key()` before calling `bind()` to create a persistent endpoint identity.
- **Retrieve the key** using `Endpoint::secret_key()` or get the public identifier with `Endpoint::id()`.
- **Store keys securely** and never enable `keylog(true)` in production environments.
- **Auto-generated keys** provide ephemeral identities suitable for temporary connections but require peer rediscovery after restarts.

## Frequently Asked Questions

### What is the difference between SecretKey and EndpointId in iroh?

The `SecretKey` is the private cryptographic material that proves your identity, while the `EndpointId` is the public derivative used by other peers to address you. The `EndpointId` is safe to share, but the `SecretKey` must be kept confidential to prevent impersonation.

### How do I persist an endpoint identity across application restarts?

Serialize your `SecretKey` to secure storage (such as a file with restricted permissions or a hardware security module) after first generation. On subsequent starts, deserialize the key and pass it to `Endpoint::builder().secret_key(your_key)` before binding. This ensures your `EndpointId` remains constant.

### Is it safe to enable key logging in production?

No. The `keylog(true)` method, found at lines 324–332 in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs), writes TLS secrets to disk for debugging purposes. Enabling this in production exposes all cryptographic material and compromises connection security. Use it only during development.

### What happens if I don't provide a SecretKey when building an endpoint?

If no key is supplied, `Builder::bind()` automatically generates a random `SecretKey` at lines 226–227 in [`iroh/src/endpoint.rs`](https://github.com/n0-computer/iroh/blob/main/iroh/src/endpoint.rs). This results in a new random `EndpointId` for every session, which is suitable for ephemeral connections but prevents peers from maintaining long-term address caches for your node.