Stop Leaking Your API Keys - Implementing a Next-Level GraphQL Proxy | awixor post

In the world of Web3, developer experience often clashes with security. We want to build fast, reactive dApps, but we often leave our frontends vulnerable by exposing sensitive API keys in the client-side bundle.

If you are building a dApp that relies on subgraphs, you've likely dropped an API key into a .env file and called it a day. But if that key is used in a client-side fetch, anyone with a "Network Tab" and a bit of curiosity can steal it.

Here is how to implement an API Proxy to take your dApp security to the next level.

The Problem: The "Client-Side Leak"

When you query a subgraph directly from a React, Vue, or vanilla JavaScript frontend, your API key is included in the request. This leads to three major risks:

Visibility: The key is plain to see in the browser's developer tools.
Theft: Malicious actors can "sniff" your key and use it to query data on your budget.
Spoofing: Even with domain restrictions, headers can occasionally be spoofed, and keys can be used in scripts outside your website.

The Solution: The API Proxy

Instead of the browser talking directly to a decentralized gateway or an indexer, we introduce a middleman: our own server.

The flow changes from:

Old Way: Client → Subgraph Gateway (Key Leaked)
Secure Way: Client → Your Server (Proxy) → Subgraph Gateway (Key Hidden)

Step 1: Secure Your Environment Variables

First, create a central environment manager. This uses @t3-oss/env-nextjs and Zod to validate your keys at build time and runtime.


typescript
1// env/server.ts
2import { createEnv } from "@t3-oss/env-nextjs";
3import { z } from "zod";
4
5export const env = createEnv({
6  server: {
7    // Ensuring the API key is the correct length for extra security
8    API_KEY: z.string().min(32).max(32),
9    // A fallback for local development
10    ROOT_URI: z.string().url().default("http://localhost:3000/api/graphql"),
11  },
12  runtimeEnv: {
13    API_KEY: process.env.API_KEY,
14    ROOT_URI: process.env.ROOT_URI,
15  },
16});

Create your .env.local file:


bash
1API_KEY=your_secret_key_here
2ROOT_URI='http://localhost:3000/graphql'

⚠️ Don't use the NEXT_PUBLIC_ prefix for sensitive keys.

Step 2: Create the API Proxy Route

1. Define the Validation Schema

To prevent malicious actors from sending malformed requests to your proxy, we use Zod to validate the incoming request body. This ensures the "shape" of the GraphQL query is correct before we even attempt to forward it.


typescript
1// app/graphql/route.ts
2import { z } from "zod";
3
4const GraphqlReqSchema = z.object({
5  query: z.string().min(1),
6  operationName: z.string().optional().nullable(),
7  variables: z.record(z.string(), z.unknown()).optional().nullable(),
8});

2. Initialize the Hidden GraphQL Client

On the server side, we initialize the GraphQLClient. This client is configured once with your protected URL and the Authorization header.


typescript
1// app/graphql/route.ts
2import { GraphQLClient } from "graphql-request";
3
4const SUBGRAPH_URL =
5  "https://api.studio.thegraph.com/query/your-id/subgraph-name/version/latest";
6
7const client = new GraphQLClient(SUBGRAPH_URL, {
8  headers: {
9    Authorization: `Bearer ${process.env.SUBGRAPH_API_KEY}`,
10  },
11});

3. Create the Proxy Logic

Now, we create a central process function. This function handles the validation, the execution, and the error reporting. By using safeParse, we can return a clean 400 Bad Request if the frontend sends something invalid.


typescript
1// app/graphql/route.ts
2import { NextResponse } from "next/server";
3
4async function processRequest(request: Request) {
5  const body = await request.json();
6  const parsed = GraphqlReqSchema.safeParse(body);
7
8  if (!parsed.success) {
9    return NextResponse.json({ error: parsed.error }, { status: 400 });
10  }
11
12  const { query, variables } = parsed.data;
13
14  try {
15    const gqlResponse = await client.request(query, variables ?? undefined);
16    return NextResponse.json({ data: gqlResponse }, { status: 200 });
17  } catch (error) {
18    return NextResponse.json(
19      { error: "Upstream request failed" },
20      { status: 500 },
21    );
22  }
23}

4. Export the API Handlers

Finally, we expose this logic via GET and POST methods in our Next.js route file. This allows your frontend to fetch data using standard HTTP methods.


typescript
1// app/graphql/route.ts
2export async function GET(request: Request) {
3  return processRequest(request);
4}
5
6export async function POST(request: Request) {
7  return processRequest(request);
8}

Step 3: The "Dual-Client" Optimization

Now that our proxy route is live, we face a new challenge: Efficiency.

When Next.js renders a page on the server (SSR), it shouldn't have to make an HTTP request to its own API route — that's like calling your own house from the kitchen to ask what's for dinner. Instead, we want our server to talk directly to the Subgraph, while the browser continues to use the Proxy.

1. Creating the SSR Client (Server-Only)

Create a client that is only ever used on the server. Because this code never touches the browser, it is safe to use the secret API key and the direct Subgraph URL.


typescript
1// lib/graphql/ssr.client.ts
2import { GraphQLClient } from "graphql-request";
3import { env } from "@/env/server";
4
5export const client = new GraphQLClient(env.ROOT_URI);

2. Creating the Browser Client (Proxy-Only)

This client is designed for your 'use client' components. It is hardcoded to point to the /graphql route we just built.


typescript
1// lib/graphql/client.ts
2import { GraphQLClient } from "graphql-request";
3
4const getGraphQLUrl = () => {
5  if (typeof window !== "undefined") {
6    return `${window.location.origin}/graphql`;
7  }
8  return "/graphql";
9};
10
11export const client = new GraphQLClient(getGraphQLUrl());

Step 4: Writing Universal Fetchers

The "Next Level" secret is making your data-fetching logic Client-Agnostic. You don't want to write one function for the server and one for the browser. Instead, you write a single function that accepts any GraphQLClient.


typescript
1// services/messages.service.ts
2export type QueryAllMessagesArgs = {
3  client: GraphQLClient;
4  vars?: GetAllMessagesQueryVariables;
5};
6
7export async function queryAllMessages({ client, vars }: QueryAllMessagesArgs) {
8  const GET_MESSAGES = `...your gql query...`;
9  const data = await client.request(GET_MESSAGES, vars);
10  return data.messages || [];
11}

For better DevEx and better type safety, you should export your queries from a dedicated graphql/queries.ts file using the GraphQL Code Generator client-preset:


typescript
1export const GET_ALL_MESSAGES = graphql(`…your gql query…`);

Step 5: Implementing in the UI

Now, you simply "inject" the correct client based on where your code is running.


typescript
1// app/messages/page.tsx
2const messages = await queryAllMessages({ client: ssrClient });

⚠️ Make sure to use the correct client, based on the rendering context, or the app will crash.

Extra Step: Prefetching on the Server

To get the best possible performance, you should prefetch your data on the server using TanStack Query. This allows you to "prime" the cache so that the data is already there when the client-side React components mount.


typescript
1// app/messages/page.tsx
2import { QueryClient } from "@tanstack/react-query";
3import { client } from "@/graphql/ssr.client";
4import { queryAllMessages } from "@/lib/graphql/fetchers";
5
6export default async function Page() {
7  const queryClient = new QueryClient();
8
9  await queryClient.prefetchQuery({
10    queryKey: ["messages", "all"],
11    queryFn: () => queryAllMessages({ client }),
12  });
13
14  // Hydrate the client with the prefetched data
15  return (
16    <HydrationBoundary state={dehydrate(queryClient)}>
17      <MessagesList />
18    </HydrationBoundary>
19  );
20}

Why This Matters

Security in Web3 isn't just about the smart contract; it's about the infrastructure that connects your users to that data. By hiding your API keys behind a proxy, you move from a "vulnerable-by-default" setup to a professional, hardened architecture.

References

Next.js API Routes Documentation
- https://nextjs.org/docs/app/building-your-application/routing/route-handlers
- Official guide for creating API routes in Next.js
GraphQL Request Documentation
- https://github.com/jasonkuhrt/graphql-request
- Lightweight GraphQL client library
Zod Schema Validation
- https://zod.dev
- TypeScript-first schema validation library
T3 Env - Environment Variable Validation
- https://env.t3.gg
- Type-safe environment variable management for Next.js
TanStack Query Documentation
- https://tanstack.com/query/latest
- Powerful async state management library