How do you secure a GraphQL API?

What makes GraphQL a different security problem?

GraphQL lets a client ask for exactly the fields it needs in one request to one endpoint. The schema names types and fields, queries read data, mutations write it, and resolvers fetch each field. That flexibility is the product feature and the attack surface: one HTTP request can contain many operations, aliases, and nested selections that a request-count limit never sees.

A REST rate limit often maps one request to one resource. A GraphQL POST can batch users, expand friends ten levels deep, or alias the same field a hundred times. You still need HTTP-level bot detection and rate limits, but you also need schema-aware controls: timeouts, depth and alias caps, query cost, authentication, and per-object authorization in the resolver.

For more information about the API baseline that still applies, see API security best practices. For more information about HTTP-level algorithms, see rate limiting algorithms.

How do GraphiQL and introspection help attackers?

GraphiQL (often at /graphql, /playground, or /console) autocompletes fields and returns detailed validation errors. A malformed query can tell an attacker which arguments conflict, which fields exist, and how to fix the syntax. Treat the playground as a development tool, not a production feature.

Introspection is enabled by default on most GraphQL servers. A client can send __schema and receive every type, field, argument, and mutation. That is a machine-readable map of the attack surface. Disable introspection in production, or restrict it to authenticated operators. Disabling GraphiQL alone is not enough if introspection or field suggestions still run.

How do batch, alias, duplication, and circular queries cause denial of service?

These techniques all aim to spend more resolver work than the HTTP request count suggests.

Query batching. HTTP batching sends an array of separate operations in one request body. If you do not cap the batch size, an attacker enumerates IDs, brute-forces a login mutation, or fans out reads while a request-count limiter sees one hit.

1
[
2
  { "query": "query { userInfo(id: \"1\") { name email } }" },
3
  { "query": "query { userInfo(id: \"2\") { name email } }" },
4
  { "query": "query { userInfo(id: \"3\") { name email } }" }
5
]

Apollo Server 4 and 5 reject this by default: allowBatchedHttpRequests is false, and turning it on is what creates the exposure. You cannot express this as repeated fields inside a single operation, because two userInfo fields with different arguments and no alias fail the spec's overlapping-fields validation before any resolver runs. That is what aliases are for, which is the next technique.

Aliases. Even when batching is off, aliases let the client fetch the same field many times with different arguments.

1
query {
2
  user1: userInfo(id: "1") {
3
    name
4
    email
5
  }
6
  user2: userInfo(id: "2") {
7
    name
8
    email
9
  }
10
  user3: userInfo(id: "3") {
11
    name
12
    email
13
  }
14
}

Duplication. Repeating the same fields in one selection set forces the server to parse and, depending on the implementation, resolve them again.

Circular or deep queries. Nested list fields such as friends { friends { friends { ... } } } walk the graph until the process runs out of time or memory. Without a max depth or a cost cap, a single well-formed query is enough.

How do injection attacks reach GraphQL resolvers?

Queries and mutations are untrusted input. If a resolver concatenates an argument into SQL, HTML, a shell command, or an outbound URL, the usual injection classes apply.

• XSS. A mutation that stores bio and a profile page that renders it as HTML can persist a script. Sanitize or encode at the output boundary; a GraphQL type of String is not a sanitizer.
• SQL injection. userInfo(id: "admin' OR '1'='1'") is only dangerous if the resolver interpolates id into a query string. Use parameterized queries. GraphQL does not protect the database.
• SSRF. A mutation that fetches url on behalf of the client can reach link-local or VPC hosts. Allow only required schemes and hosts, and check resolved addresses.
• Command injection. Passing a user string into wget, convert, or a shell is the same bug it is in REST.

Validate arguments with an explicit schema (length, pattern, enum, ID format) before the resolver touches storage or the network.

Which GraphQL attack vectors should you mitigate first?

The following table maps each vector to the risk and the control that actually stops it.

Layer the controls. An HTTP rate limit without query cost still admits one expensive document. Query cost without authentication still serves the graph to strangers.

How do you add Arcjet and GraphQL Armor to Apollo Server 5?

Apollo Server 5.x is current (@apollo/server 5.5.x at the time of writing). GraphQL Armor 3.2 supports Apollo Server 4 and 5. Pin @arcjet/node@1.10.0, not the old 1.0.0-alpha.28 line.

Keep graphql on the 16 line here. graphql 17 is released, but Apollo Server 5 declares a ^16.11.0 peer dependency, so installing 17 alongside it gives you a peer warning and an unsupported combination. graphql-yoga does accept 15, 16, or 17 if that is the server you run.

GraphQL Armor also has peer dependencies that npm will not install for you: @envelop/core and an exact @escape.tech/graphql-armor-types@0.7.0, which is where the GraphQLArmorConfig type below comes from.

1
npm install @apollo/server@^5.5.0 graphql@^16.14.0 @arcjet/node@1.10.0 \
2
  @escape.tech/graphql-armor@^3.2.0 @envelop/core@^5.0.0 \
3
  @escape.tech/graphql-armor-types@0.7.0

Create a client with a token bucket and a bot allow list. interval is seconds. Pass { requested } on every protect() call so each HTTP request spends a known number of tokens.

1
import { ApolloServer } from "@apollo/server";
2
import { startStandaloneServer } from "@apollo/server/standalone";
3
import { ApolloServerPluginLandingPageDisabled } from "@apollo/server/plugin/disabled";
4
import { ApolloArmor } from "@escape.tech/graphql-armor";
5
import type { GraphQLArmorConfig } from "@escape.tech/graphql-armor-types";
6
import arcjet, { detectBot, tokenBucket } from "@arcjet/node";
7
import { GraphQLError } from "graphql";
8
import type { IncomingMessage } from "node:http";
9

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

26
const armorConfig: GraphQLArmorConfig = {
27
  maxAliases: { n: 3 },
28
  maxDepth: { n: 5 },
29
  maxTokens: { n: 1000 },
30
  blockFieldSuggestion: { enabled: true },
31
  costLimit: {
32
    maxCost: 100,
33
    objectCost: 2,
34
    scalarCost: 1,
35
    depthCostFactor: 1.5,
36
  },
37
};
38

39
const armor = new ApolloArmor(armorConfig);
40
const protection = armor.protect();

startStandaloneServer is fine for a local demo. In production, mount Apollo on Express or Fastify so you control HTTP timeouts, TLS, and middleware order. Disable the landing page and introspection when the server is reachable from the public internet.

How do you authenticate and authorize GraphQL operations?

A valid token is not permission to read every User or call every mutation. Authenticate in context, then authorize in the resolver with the principal, tenant, requested object, and operation.

1
type Principal = {
2
  id: string;
3
  role: "admin" | "member";
4
  tenantId: string;
5
};
6

7
type Context = { user: Principal | null };
8

9
async function userFromAuthorization(
10
  header: string | undefined,
11
): Promise<Principal | null> {
12
  if (!header?.startsWith("Bearer ")) {
13
    return null;
14
  }
15
  // Verify signature, issuer, audience, and expiry. Then load tenant and role.
16
  return verifyAccessToken(header.slice("Bearer ".length));
17
}
18

19
// Replace with your JWT or session verifier.
20
declare function verifyAccessToken(token: string): Promise<Principal | null>;
21

22
type User = Principal & { name: string; email: string; bio?: string };
23
const users: User[] = [];
24

25
const typeDefs = `#graphql
26
  type User {
27
    id: ID!
28
    name: String!
29
    email: String!
30
    bio: String
31
    friends: [User!]!
32
  }
33

34
  type Query {
35
    userInfo(id: ID!): User
36
  }
37

38
  type Mutation {
39
    changeUserInfo(id: ID!, name: String!, bio: String): User
40
  }
41
`;
42

43
const resolvers = {
44
  Query: {
45
    userInfo(_parent: unknown, { id }: { id: string }, ctx: Context) {
46
      const principal = ctx.user;
47
      if (!principal) {
48
        throw new GraphQLError("Unauthenticated", {
49
          extensions: { code: "UNAUTHENTICATED" },
50
        });
51
      }
52
      const user = users.find((u) => u.id === id);
53
      if (!user || user.tenantId !== principal.tenantId) {
54
        throw new GraphQLError("Not found", {
55
          extensions: { code: "FORBIDDEN" },
56
        });
57
      }
58
      return user;
59
    },
60
  },
61
  Mutation: {
62
    changeUserInfo(
63
      _parent: unknown,
64
      args: { id: string; name: string; bio?: string },
65
      ctx: Context,
66
    ) {
67
      const principal = ctx.user;
68
      if (!principal) {
69
        throw new GraphQLError("Unauthenticated", {
70
          extensions: { code: "UNAUTHENTICATED" },
71
        });
72
      }
73
      const isSelf = principal.id === args.id;
74
      if (principal.role !== "admin" && !isSelf) {
75
        throw new GraphQLError("Not allowed", {
76
          extensions: { code: "FORBIDDEN" },
77
        });
78
      }
79
      if (
80
        !/^[a-zA-Z0-9. ]+$/.test(args.name) ||
81
        (args.bio?.length ?? 0) > 100
82
      ) {
83
        throw new GraphQLError("Invalid input", {
84
          extensions: { code: "BAD_USER_INPUT" },
85
        });
86
      }
87
      const user = users.find(
88
        (u) => u.id === args.id && u.tenantId === principal.tenantId,
89
      );
90
      if (!user) {
91
        throw new GraphQLError("Not found", {
92
          extensions: { code: "FORBIDDEN" },
93
        });
94
      }
95
      user.name = args.name;
96
      if (args.bio !== undefined) {
97
        user.bio = args.bio;
98
      }
99
      return user;
100
    },
101
  },
102
};
103

104
const server = new ApolloServer<Context>({
105
  typeDefs,
106
  resolvers,
107
  introspection: false,
108
  plugins: [...protection.plugins, ApolloServerPluginLandingPageDisabled()],
109
  validationRules: protection.validationRules,
110
});
111

112
const { url } = await startStandaloneServer(server, {
113
  listen: { port: 4000 },
114
  async context({ req }: { req: IncomingMessage }): Promise<Context> {
115
    const decision = await aj.protect(req, { requested: 1 });
116
    if (decision.isDenied()) {
117
      throw new GraphQLError("Forbidden", {
118
        extensions: {
119
          http: {
120
            status: decision.reason.isRateLimit() ? 429 : 403,
121
          },
122
        },
123
      });
124
    }
125
    return { user: await userFromAuthorization(req.headers.authorization) };
126
  },
127
});
128

129
console.log(`Server ready at ${url}`);

Look up the record by ID and tenant. An opaque ID is not proof of access. Apply the same check to child fields (friends, exports, files). A support role that may read userInfo should not automatically call changeUserInfo. For more information about object-level authorization, see API security best practices.

How do you calculate and cap query cost?

HTTP rate limits count requests. Query cost counts work. Assign a cost to scalars, objects, and list fields so that friends is more expensive than name, and so that each extra level of nesting multiplies the total. Reject the document during validation when the estimate exceeds maxCost.

GraphQL Armor's costLimit does that estimate for you. Tune the knobs against real queries from your clients:

• maxCost is the ceiling for one operation.
• objectCost and scalarCost are the base weights.
• depthCostFactor raises the price of each nested level, which is how you stop circular friends walks without guessing a single magic depth.

You can also attach explicit weights in the resolver layer when a field is known to be expensive (full-text search, export, AI). Charge more tokens on the Arcjet requested argument for those operations, and keep the Armor cap as a backstop for anonymous document shape.

1
const decision = await aj.protect(req, {
2
  requested: operationName === "ExportUsers" ? 20 : 1,
3
});

A timeout around execution is the last stop: cost estimates assume typical resolver time. A resolver that hits a slow dependency can still overrun. Set an execution deadline and cancel downstream work when it fires.

Persisted operations shrink the problem further: the server only runs hashes it already approved, so an attacker cannot invent a new circular query. For more information about Yoga, token buckets, bot allow lists, and the SHA-256 persisted-operation flow, see GraphQL rate limiting and bot detection.