API Keys - iroh

API keys authenticate your endpoint to Iroh Services. Iroh itself is permissionless — connections between two endpoints never need authorization — but the resources in your project belong to you. Your API key is what lets an endpoint push data into your project and connect to your project’s Shared or Dedicated relays.

What API keys authorize

API keys are required for:

Uploading metrics from endpoints to your project
Sending network diagnostics reports from endpoints to your project
Connecting to your project’s Shared or Dedicated relays, which require authentication by default

API keys are not required for:

Connecting through the public relays
NAT traversal connections to other iroh endpoints

Get an API key

After signing in, create a new project. This is your sandbox for all endpoints, the control center where you manage relays, metrics, and networks.

Then navigate to your project’s Settings → API Keys tab and click Create API Key. The key is shown once on creation, so copy it somewhere safe.

The environment variable used by the Rust client is IROH_SERVICES_API_SECRET (named for legacy reasons; same thing as your API key).

Use it in your app

Pass the key to iroh_services::preset(), bind your endpoint with the preset, then hand the same preset to the client:

use iroh::Endpoint;

let preset = iroh_services::preset()
    .api_secret_from_str("YOUR_API_KEY")?
    .build()?;

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

let client = preset.client_builder(&endpoint).build().await?;

The preset carries the key, so you don’t pass it to the client a second time. The literal string above is for illustration. Load the key from an environment variable or a secret manager instead, using api_secret_from_env() to read IROH_SERVICES_API_SECRET. For a full walkthrough (creating an endpoint, naming it, and verifying it on the dashboard) see the Iroh Services quickstart.

How relay authentication works

The API key is a long-lived, project-wide signing secret. The SDK does not send that secret to a relay. Instead, when you build an endpoint with iroh_services::preset(), it uses the API key locally to sign a capability token that:

Is bound to that endpoint’s Endpoint ID
Grants only relay-use capability for the relay connection
Expires after 30 days by default

The endpoint presents this token when it connects. The relay verifies the token signature, Endpoint ID, capability, and expiry, and checks that the issuing API key is still allowed for the project. On relays with authentication enabled, deleting an API key removes that issuer and disconnects connections authenticated by it.

An API key is a project-wide secret

The token is endpoint-bound, but the API key itself is not an endpoint-scoped credential. Any process holding the key can mint valid tokens for endpoint identities it controls, push metrics, send diagnostics reports, and connect to your project’s managed relays. Treat the API key as the root credential for the whole project. API keys are a building block for your own authentication system, not a replacement for one. If your app runs on machines you don’t control, you decide who gets access, and the key stays on your side. Keep the key on endpoints you operate. If you can control the machine’s disk and process environment, and whether you can rotate the key on it without shipping a new release. If both are yes, the key is recoverable. On an enterprise deployment where machines are enrolled in an MDM, the key is delivered as a managed configuration or platform secret rather than compiled into the app, and you can rotate or revoke it across the fleet from the console. Those endpoints are infrastructure you operate in every sense that matters here, so metrics, net diagnostics, and authenticated dedicated relays all work as intended. What doesn’t work so well is a consumer application on a device you don’t administer. In those cases, you’ll need to build your own authentication layer that allows you to control authentication with your own token, service, or otherwise. On it’s own, iroh is not opinionated about authentication so you can use whatever system you want, forever.

What’s next

We’re working on separately issued per-endpoint access through your own application server: your backend authenticates a user, then hands that user’s endpoint a credential without your project API key ever touching the device. This credential-issuance flow is not implemented yet. The endpoint-bound capability token described above does not replace it because the process that mints that token still possesses the project-wide API key. If your use case needs this, contact us — we want to hear about the shape of it.

​What API keys authorize

​Get an API key

​Use it in your app

​How relay authentication works

​An API key is a project-wide secret

​What’s next