UNAUTHENTICATED — missing x-api-key

Root causes

Ranked by frequency. First cause is the one to check first.

1. 01API key passed at channel creation but not as request metadata — most providers require per-call metadata.
2. 02Using `Authorization: Bearer` when the provider expects `x-api-key`, or vice versa.
3. 03API key has leading/trailing whitespace from copy-paste (Subglow trims on server; some providers reject silently).
4. 04API key was rotated in the dashboard but the deploy still uses the old one.
5. 05Using a free-trial key that expired — trials auto-expire after the 14-day window.

Fix steps

1. 1

   Attach the key as request metadata, not channel options

   In TypeScript: `await client.subscribe({ 'x-api-key': KEY })`. In Python: `stub.Subscribe(req, metadata=(('x-api-key', KEY),))`. In Rust: add `.add_metadata('x-api-key', KEY)` to the interceptor.

2. 2

   Use the exact header name the provider expects

   Subglow and Chainstack use `x-api-key`. Triton One uses `authorization: Bearer <token>`. Helius Laserstream uses the key in the URL path, not as metadata. Mismatched headers always yield UNAUTHENTICATED.

3. 3

   Trim whitespace

   `const key = process.env.SUBGLOW_API_KEY?.trim()`. A single newline from your secret manager silently breaks gRPC metadata.

4. 4

   Verify the key directly

   Run `grpcurl -H 'x-api-key: YOUR_KEY' grpc.subglow.io:443 geyser.Geyser/GetVersion`. A successful GetVersion response confirms the key is valid and attached correctly. If that fails too, regenerate the key in your Subglow dashboard.

Code example

use yellowstone_grpc_client::GeyserGrpcClient;
use tonic::transport::ClientTlsConfig;

let tls_config = ClientTlsConfig::new().with_native_roots();
let mut client = GeyserGrpcClient::build_from_shared("https://grpc.subglow.io:443")?
    .x_token(Some("YOUR_API_KEY"))?
    .tls_config(tls_config)?
    .connect()
    .await?;

// x-api-key is automatically attached to every call by the x_token interceptor.
let (mut subscribe_tx, mut stream) = client.subscribe().await?;

Related errors

• UNAVAILABLE: connection refused
  Your gRPC client got `Status { code: Unavailable }` with `connection refused` (or `transport is closing`). The TCP handshake never completed — either you're hitting the wrong port, TLS is misconfigured, or the endpoint is genuinely down.
• Free trial expired — API key invalid
  Your free-trial API key was valid for 14 days and has expired. Streams will terminate with UNAUTHENTICATED and JSON-RPC calls will return 401. Upgrade to Sniper ($99/mo) or Pro ($249/mo) to keep the same key active.
• TLS handshake failed on grpc.subglow.io
  The TCP socket opened but TLS negotiation failed. Usually a stale root CA bundle inside a Docker image, a missing SNI extension, or a corporate MITM proxy intercepting and presenting its own certificate.