Ephemeral Keys

​

When to use Ephemeral Keys

• Client-side apps - a browser SPA or mobile app that calls GoldRush directly, where any embedded API key is trivially extractable from network traffic or bundled JS.
• WebSockets - the Hyperliquid WebSocket (wss://hypercore.goldrushdata.com/ws) takes its credential as a key query parameter at connect time. That URL is visible to the client, so it must not carry your API key.
• High-fan-out embeds - thousands of end users each holding a credential. With Ephemeral Keys, each client gets its own short-lived token that self-expires within one refresh window.

​

The security model

1. Your API key never reaches the client. Only your backend holds it. It is used once per refresh, server-to-server, to mint an Ephemeral Key.
2. Ephemeral Keys inherit the parent’s access. An Ephemeral Key carries exactly the parent API key’s bindings - never wider, and in this release never narrower. The edge enforces the parent’s access on every request, and all usage attributes to the parent, so quotas and billing are unchanged. (Per-child scope narrowing is planned but not part of this release.)
3. Ephemeral Keys are safe if stolen. They are signed RS256 JWTs with a 30-minute expiry. An attacker who captures one from a browser or a WS URL can use it only until it expires - a small, self-healing blast radius. No secret is recoverable from the token.

​

The 30-minute TTL

• Too short and clients refresh constantly, adding mint load.
• Too long and a stolen token stays useful.
• 30 minutes keeps the leaked-token window small while a client only mints ~48 times a day.

​

Lifecycle: mint → embed → refresh

                                         ╔═ GoldRush control plane ═════════╗
╔══════════════════╗                     ║                                  ║░
║ Your backend     ║░                    ║   authenticate cqt_… · mint a    ║░
║ (holds API key)  ║░ ──① POST mint ───▶ ║   30-min RS256 JWT (gr_ek_…)     ║░
╚════════╤═════════╝░                    ║                                  ║░
 ░░░░░░░░│░░░░░░░░░░░                    ╚══════════════════════════════════╝░
                                          ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
         │ ② hand gr_ek_… to the client
         ▼
                                         ╔═ GoldRush edge ══════════════════╗
╔══════════════════╗                     ║                                  ║░
║ Client / browser ║░                    ║   offline-verify the JWT against ║░
║ (untrusted)      ║░ ──③ key=gr_ek_… ─▶ ║   JWKS · no mint round-trip      ║░
╚════════╤═════════╝░                    ║                                  ║░
 ░░░░░░░░│░░░░░░░░░░░                    ╚══════════════════════════════════╝░
                                          ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
         │ ④ ~5 min before exp: mint a fresh key and swap it in
         ▼
       (refresh loop repeats)

1. Mint (server-side). Your backend calls POST /platform/ephemeral_keys/ with your API key and gets back { ephemeral_key, expires_at }.
2. Embed (client-side). Your backend passes the gr_ek_… token to the client, which uses it exactly where it would have used an API key - as a key query parameter, a bearer token, or Basic Auth.
3. Refresh (client-side). Shortly before expires_at, the client asks your backend for a fresh Ephemeral Key and swaps it in. For long-lived WebSocket connections, reconnect (or re-authenticate) with the new token before the old one expires.

​

Quick start (curl)

curl -X POST "https://api.covalenthq.com/platform/ephemeral_keys/" \
  -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 1800}'
# → { "ephemeral_key": "gr_ek_eyJhbGciOiJSUzI1NiIsImtpZCI6…", "expires_at": "2026-08-03T18:30:00+00:00" }

# Bearer token
curl -X GET "https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/" \
  -H "Authorization: Bearer $GOLDRUSH_EPHEMERAL_KEY"

# or as a query parameter (handy for URLs the client already holds)
curl -X GET "https://api.covalenthq.com/v1/eth-mainnet/address/demo.eth/balances_v2/?key=$GOLDRUSH_EPHEMERAL_KEY"

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_EPHEMERAL_KEY"

​

API reference

​

Mint an Ephemeral Key

POST /platform/ephemeral_keys/

{
  "ephemeral_key": "gr_ek_eyJhbGciOiJSUzI1NiIsImtpZCI6…",
  "expires_at": "2026-08-03T18:30:00+00:00"
}

​

Ephemeral JWKS endpoint

GET /platform/.well-known/ephemeral-jwks.json

{
  "keys": [
    { "kty": "RSA", "use": "sig", "alg": "RS256", "kid": "ek-2026-08a", "n": "…", "e": "AQAB" }
  ]
}

​

Token claims

​

Error codes

​

Recipes

​

Recipe A - Node/Express mint proxy

1. The proxy is not open. It sits behind your app’s existing user session (cookie, session token, or whatever you already use to know who is logged in). A random visitor with no session gets 401 and never mints anything. Only your authenticated users can obtain a token, so nobody can run up your bill by hammering the endpoint. That is the job of requireYourUserAuth below - your own auth middleware, not something GoldRush provides.
2. The token it returns is safe to hold in the browser. An Ephemeral Key is meant to live in an untrusted client - it is a 30-minute, parent-scoped, secret-free JWT (see the security model). What must never reach the browser is your API key; the Ephemeral Key reaching the browser is the whole point.

// server.js - never ships to the client
import express from "express";

const app = express();
const GOLDRUSH_API_KEY = process.env.GOLDRUSH_API_KEY; // cqt_… - server-side secret

// requireYourUserAuth is YOUR existing session check - e.g. verify the session
// cookie / auth token on req and reject with 401 if the caller isn't logged in.
// GoldRush does not provide this; it's the same auth that guards your other
// authenticated routes.
app.post("/api/goldrush-ephemeral-key", requireYourUserAuth, async (req, res) => {
  const r = await fetch("https://api.covalenthq.com/platform/ephemeral_keys/", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${GOLDRUSH_API_KEY}`,
      "Content-Type": "application/json",
    },
    // Only ttl_seconds is accepted today; the token inherits the API key's access.
    body: JSON.stringify({ ttl_seconds: 1800 }),
  });

  if (!r.ok) {
    return res.status(502).json({ error: "mint_failed", status: r.status });
  }
  const { ephemeral_key, expires_at } = await r.json();
  // Hand only the short-lived token to the client - never the API key.
  res.json({ ephemeral_key, expires_at });
});

app.listen(3000);

​

Recipe B - Browser WebSocket with auto-refresh

import { EphemeralKeyProvider } from "@covalenthq/client-sdk";

// Points at YOUR backend proxy, not directly at GoldRush.
const keys = new EphemeralKeyProvider({
  mintUrl: "/api/goldrush-ephemeral-key",
  refreshSkewSeconds: 300, // refresh ~5 min before exp
});

async function connect() {
  const token = await keys.getToken(); // mints on first call, cached after
  const ws = new WebSocket(`wss://hypercore.goldrushdata.com/ws?key=${token}`);

  ws.onopen = () => {
    ws.send(JSON.stringify({ method: "subscribe", subscription: { type: "l2Book", coin: "BTC" } }));
  };
  ws.onmessage = (ev) => handleBookUpdate(JSON.parse(ev.data));

  // A stale/expired token closes the socket with a 401-class reason: reconnect with a fresh one.
  ws.onclose = async () => {
    await keys.refresh();      // force a new token
    setTimeout(connect, 1000); // reconnect with jittered backoff in production
  };
}

// Proactively reconnect before the current token expires, so the socket never
// drops mid-stream. Ephemeral Keys can't hold a connection open past their exp.
keys.onBeforeExpiry(() => connect());

connect();

​

FAQ

• Do Ephemeral Keys change my billing? No. All usage attributes to the parent API key’s parent_key_id, exactly as if the parent had made the calls. There is no separate meter or plan for Ephemeral Keys.
• Can I mint an Ephemeral Key from another Ephemeral Key? No. Only a parent API key (cqt_… / ckey_…) can mint. Minting with a gr_ek_… token is rejected - this prevents a leaked client token from bootstrapping fresh long-lived access.
• Can I restrict what an Ephemeral Key can do (per-child scopes)? Not in this release. A token inherits exactly the parent API key’s access - it can’t be widened, and per-child narrowing (fewer chains/endpoints) is planned but not yet available. The only mint-time parameter today is ttl_seconds.
• If the browser calls my mint proxy, can’t anyone call it and steal a token? No. Your mint proxy sits behind your app’s own login (the requireYourUserAuth step in Recipe A) - an unauthenticated request gets 401 and mints nothing, so nobody can run up your bill. And a token handed to one of your legitimate users is safe to hold client-side anyway: it is a 30-minute, parent-scoped, secret-free JWT. The thing that must stay server-side is your API key, never the Ephemeral Key.
• Is this the same as a ServiceKey? No - different job. ServiceKeys authenticate account-level Platform operations (like reading your usage) and are rejected on the data APIs. Ephemeral Keys authenticate data requests on behalf of a parent API key and are for client-side embedding. See also Authentication for server-side API-key usage.