How do you add rate limits and bot detection to a GraphQL API?

How do you add rate limits and bot detection to a GraphQL API?

Put the HTTP controls on the route that serves GraphQL, then add schema-aware limits so one document cannot do the work of a thousand REST calls. A request-count limiter sees one POST. The document inside that POST can batch users, alias the same field, or walk friends until the process tips over. You need both layers: a token bucket and bot allow list on the HTTP request, and persisted operations so the server only runs queries it already hashed.

This guide uses GraphQL Yoga on the Next.js App Router with @arcjet/next. Yoga is a good fit because createYoga exposes handleRequest that speaks the Fetch API. Arcjet's Next.js adapter accepts that same Request. Call protect() in GET and POST before you forward the request to Yoga. Do not put the limiter only in a Next.js middleware matcher and assume GraphQL is covered; run it on the route that parses the document.

For more information about GraphQL attack classes and resolver authorization, see how to secure a GraphQL API. For more information about token bucket versus fixed or sliding windows, see rate limiting algorithms.

What do you install?

Create a Next.js app if you do not already have one, then pin the adapters:

1
npm install graphql-yoga@^5.22.0 graphql@^16.14.0 @arcjet/next@1.10.0

Add ARCJET_KEY to .env.local from the Arcjet dashboard. Keep the key out of the client bundle; the GraphQL route runs on the server.

How do you rate-limit GraphQL with a token bucket?

Create src/app/api/graphql/route.ts. interval accepts either a number of seconds or a duration string, so interval: 10 and interval: "10s" are the same rule. Pick one form and keep it consistent across a codebase. refillRate is how many tokens return each interval. capacity is the burst ceiling. Pass { requested } on every protect() call; that is how token bucket expresses variable cost. Sliding and fixed windows count events and have no requested field.

1
import arcjet, { detectBot, tokenBucket } from "@arcjet/next";
2
import { createSchema, createYoga } from "graphql-yoga";
3
import { NextResponse } from "next/server";
4

5
const aj = arcjet({
6
  key: process.env.ARCJET_KEY!,
7
  rules: [
8
    tokenBucket({
9
      mode: "LIVE",
10
      refillRate: 5,
11
      interval: 10,
12
      capacity: 10,
13
    }),
14
    detectBot({
15
      mode: "LIVE",
16
      allow: ["CATEGORY:SEARCH_ENGINE"],
17
    }),
18
  ],
19
});
20

21
const { handleRequest } = createYoga({
22
  schema: createSchema({
23
    typeDefs: /* GraphQL */ `
24
      type Query {
25
        greetings: String
26
      }
27
    `,
28
    resolvers: {
29
      Query: {
30
        greetings: () =>
31
          "This is the `greetings` field of the root `Query` type",
32
      },
33
    },
34
  }),
35
  graphqlEndpoint: "/api/graphql",
36
  fetchAPI: { Response },
37
});
38

39
async function protectAndHandle(req: Request) {
40
  const decision = await aj.protect(req, { requested: 5 });
41

42
  if (decision.isDenied()) {
43
    const status = decision.reason.isRateLimit() ? 429 : 403;
44
    return NextResponse.json(
45
      { error: status === 429 ? "Too Many Requests" : "Forbidden" },
46
      { status },
47
    );
48
  }
49

50
  return handleRequest(req, {});
51
}
52

53
export function GET(req: Request) {
54
  return protectAndHandle(req);
55
}
56

57
export function POST(req: Request) {
58
  return protectAndHandle(req);
59
}

requested: 5 against capacity: 10 means two full-cost requests exhaust the bucket. A cheap introspection-free read can pass { requested: 1 }; an export or nested search can pass a larger integer. After the bucket empties, further requests return 429 until refillRate tokens arrive at the next interval.

The default characteristic is the client IP. After you authenticate, key the bucket on user, API key, or tenant and pass that value into protect().

Which bots should you allow on a GraphQL API?

detectBot takes exactly one of allow or deny. On a browser product you often allow search engines and deny everything else. On an API you usually want tools and programmatic clients. The following table lists common allow-list entries.

CURL is already inside CATEGORY:TOOL, so you do not need both. An empty allow: [] blocks every detected bot, including curl. That is why a first curl http://localhost:3000/api/graphql returns 403 until you add a tool or programmatic category.

For more information about allow versus deny lists, verified bots, and spoofed user agents, see bot detection techniques.

How do you disable GraphiQL, introspection, and field suggestions?

Rate limits and bot rules do not hide the schema. GraphiQL, introspection, and autocomplete still teach an attacker the graph.

Yoga serves GraphiQL in development on GET requests that accept text/html. Turn it off with graphiql: false. Then install the introspection and suggestion plugins:

1
npm install @graphql-yoga/plugin-disable-introspection @escape.tech/graphql-armor-block-field-suggestions

1
import { useDisableIntrospection } from "@graphql-yoga/plugin-disable-introspection";
2
import { blockFieldSuggestionsPlugin } from "@escape.tech/graphql-armor-block-field-suggestions";
3

4
const { handleRequest } = createYoga({
5
  graphiql: false,
6
  plugins: [useDisableIntrospection(), blockFieldSuggestionsPlugin()],
7
  schema: createSchema({
8
    typeDefs: /* GraphQL */ `
9
      type Query {
10
        greetings: String
11
      }
12
    `,
13
    resolvers: {
14
      Query: {
15
        greetings: () =>
16
          "This is the `greetings` field of the root `Query` type",
17
      },
18
    },
19
  }),
20
  graphqlEndpoint: "/api/graphql",
21
  fetchAPI: { Response },
22
});

Disabling the playground is not a security control by itself. As long as introspection or field suggestions remain, a client can still enumerate the schema.

How do persisted operations work with SHA-256 hashes?

Persisted operations replace the query text on the wire with a hash the server already knows. The client cannot send an arbitrary document, so circular queries, unexpected mutations, and schema probing fail closed unless you registered that exact string.

The flow is:

1. Canonicalize each operation your client ships (the exact query string, including whitespace you choose to treat as significant).
2. Compute the SHA-256 digest of that string and encode it as hexadecimal.
3. Store hash → document on the server. Generate this map at build time from the client's operation files so the store cannot drift from the app.
4. The client sends only the hash. Yoga's plugin supports Automatic Persisted Queries (APQ) by default, or you can read a custom id query parameter.
5. getPersistedOperation(sha256Hash) returns the stored document or null. null means reject.

1
import { createHash } from "node:crypto";
2
import { usePersistedOperations } from "@graphql-yoga/plugin-persisted-operations";
3

4
function sha256(document: string) {
5
  return createHash("sha256").update(document).digest("hex");
6
}
7

8
const greetings = "{greetings}";
9
const typename = "{__typename}";
10

11
const store: Record<string, string> = {
12
  [sha256(typename)]: typename,
13
  [sha256(greetings)]: greetings,
14
};
15

16
const { handleRequest } = createYoga({
17
  graphiql: false,
18
  plugins: [
19
    useDisableIntrospection(),
20
    blockFieldSuggestionsPlugin(),
21
    usePersistedOperations({
22
      getPersistedOperation(sha256Hash: string) {
23
        return store[sha256Hash] ?? null;
24
      },
25
      extractPersistedOperationId(_params, request) {
26
        return new URL(request.url).searchParams.get("id");
27
      },
28
    }),
29
  ],
30
  schema: createSchema({
31
    typeDefs: /* GraphQL */ `
32
      type Query {
33
        greetings: String
34
      }
35
    `,
36
    resolvers: {
37
      Query: {
38
        greetings: () =>
39
          "This is the `greetings` field of the root `Query` type",
40
      },
41
    },
42
  }),
43
  graphqlEndpoint: "/api/graphql",
44
  fetchAPI: { Response },
45
});

A client then calls /api/graphql?id=<hex> instead of posting a query string. Any hash that is not in store is rejected. Rotate the store when you add or change operations; treat it like a deployment artifact, not a runtime guess. If two clients hash different whitespace or argument names, they produce different digests, so generate the map from the same source files the client bundles.

APQ clients send extensions.persistedQuery.sha256Hash instead of id. Use that extractor when your existing mobile or web client already speaks APQ. Either way, the server must look up the hash and refuse unknown documents. Do not fall back to executing a raw query body when the hash is missing; that fallback reopens arbitrary documents and defeats the control.

What else should you add?

HTTP token buckets and bot allow lists stop floods and unwanted automation. They do not authorize a tenant to read another tenant's userInfo, and they do not cap nested friends selections. Combine this route with query cost, max depth, and resolver authorization from how to secure a GraphQL API. Add CORS and CSRF rules if the same origin also serves a browser session.