Iroh Managed Relays Now Require API-Key Authentication by Default

Iroh has flipped the default on its managed relays: as of June 2026, every relay deployed through Iroh Services requires authentication. The change is automatic for anyone using the iroh_services preset — no config toggles, no extra code. Older relays stay open until you opt in, so existing endpoints don't break.

The motivation is straightforward. A relay URL is effectively a credential that ships inside every client you distribute and is visible to anyone sniffing a connection handshake. If the relay accepts anyone, anyone who finds that URL can push traffic through it, competing with your own traffic for finite bandwidth and connection slots. Rotating the URL doesn't help because it's baked into every client.

How authentication works

Every relay connection starts with an HTTP handshake (the same one that upgrades to WebSocket). Authentication rides in a standard header:

Authorization: Bearer <token>

The token is a signed capability token carrying four pieces of information:

• Issuer: your project's API key
• Subject: the public key of the endpoint presenting it
• Grant: permission to use the relay, and nothing else
• Expiry: a short time window, so a compromised token is useless quickly

When an endpoint connects, the relay first proves the endpoint actually owns its secret key — this happens for every connection, authenticated or not. Then it validates the token: signature, expiry, grant, subject match, and issuer. Only if all checks pass is the endpoint admitted.

Two nice properties fall out of this design:

• A leaked URL is harmless. Without a token from your API key, dialing the relay gets you nothing.
• A leaked token enables connections, but not impersonation. The token is bound to a specific endpoint public key, so presenting it from a different endpoint fails — the handshake still requires proof of ownership of that endpoint's secret key.

Revocation is equally clean. Your API key is the identity the relay recognizes, so rotating or deleting a key stops honoring tokens it issued, and active connections riding those tokens are dropped.

Connecting an endpoint

You don't assemble tokens by hand. The iroh_services preset mints the token from your API secret and attaches it to every relay connection. The code is the same few lines you'd write anyway:

use iroh::Endpoint;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let preset = iroh_services::preset()
        .relays(["https://us-east1.your-project.iroh.link"])?
        .api_secret_from_env()? // reads IROH_SERVICES_API_SECRET
        .build()?;

    let endpoint = Endpoint::bind(preset).await?;
    Ok(())
}

Your API secret never leaves your process. The preset derives a relay-scoped token from it, and only that derived token travels to the relay. Point .relays(...) at your project's relay URLs, set IROH_SERVICES_API_SECRET, and you're done.

What's next

Today every endpoint gets the same capabilities. Iroh plans to add scoped tokens (different permissions per endpoint), per-endpoint revocation, and an API to manage all of this outside the dashboard. For now, the advice stands: run at least two relays in different regions so a single region failure doesn't strand your endpoints.