Understanding and preventing unauthorised graphql queries

A graphql query unauthorised error means your API rejected the request because it could not verify who is making it, or confirmed the user does not have the required permissions. In practice you will see one of two distinct responses: an HTTP 401 with the GraphQL error code UNAUTHENTICATED (the token is missing, expired, or malformed) or an HTTP 403 / error code FORBIDDEN (the token is valid but the user lacks access to that specific field or resolver). Knowing which one you are dealing with is the fastest way to fix it.

What the error actually looks like

Before diving into solutions, it helps to see exactly what GraphQL returns when authorisation fails. Unlike REST, GraphQL almost always returns HTTP 200 even for auth errors — the real status lives inside the JSON body:

// UNAUTHENTICATED — token is missing or invalid
{
  "errors": [
    {
      "message": "Not authenticated",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"],
      "extensions": {
        "code": "UNAUTHENTICATED",
        "http": { "status": 401 }
      }
    }
  ],
  "data": { "user": null }
}

// FORBIDDEN — token is valid but user lacks permission
{
  "errors": [
    {
      "message": "Not authorised to access field 'paymentMethod'",
      "extensions": {
        "code": "FORBIDDEN",
        "http": { "status": 403 }
      }
    }
  ]
}

If you see UNAUTHENTICATED, the fix is in how you pass the token. If you see FORBIDDEN, the fix is in your resolver-level permission logic.

Introduction

GraphQL has transformed API development with its flexible query language, but that flexibility shifts security responsibility from infrastructure-level endpoint controls to application-level resolver controls. Unauthorised GraphQL queries are one of the most exploited vulnerabilities in modern APIs: the single-endpoint design means a single misconfigured resolver can expose data across your entire object graph. Understanding how authorisation failures happen — and how to prevent them at every layer — is essential for any team running GraphQL in production.

GraphQL authorisation vulnerabilities explained

GraphQL’s rapid enterprise adoption has created complex authorisation challenges that many teams underestimate. Unlike REST APIs where a route guard at /admin/users protects the entire resource, GraphQL’s single endpoint requires field-level and resolver-level authorisation checks throughout the entire query execution chain.

The OWASP API Security Top 10 consistently lists broken object-level authorisation (BOLA) as a leading category, and GraphQL is especially susceptible because of its nested relationship traversal. Many developers assume verifying identity once at the request level is sufficient — it is not. Each resolver in the execution chain can reach different data, and each needs its own permission check.

The unique security challenges of GraphQL

GraphQL’s nested query capability lets clients traverse complex object relationships in a single request. That is powerful for developers — and equally powerful for attackers. A user might have permission to read a Customer object but not the paymentMethods or internalNotes fields nested inside it. If your resolver for those fields does not independently verify permissions, the data is exposed regardless of top-level checks.

Query depth and complexity introduce additional attack vectors: deeply nested queries can bypass shallow authorisation checks, extract unauthorised data through relationship traversal, and exhaust server resources before any rate limit fires. The resolver chain model means that a failure at any depth can leak sensitive information through error messages or partial responses.

Business impacts of GraphQL authorisation flaws

A graphql query unauthorised bypass is never just a technical problem. The business consequences are immediate and lasting:

Compliance frameworks like GDPR, HIPAA, and PCI DSS impose specific access-control requirements that GraphQL authorisation failures can directly violate. Beyond fines, unauthorised query access often reveals your database structure and relationship patterns — giving attackers a map for deeper, more targeted attacks on related systems.

Anatomy of an unauthorised GraphQL query

An unauthorised query succeeds when the authorisation logic fails to validate permissions at one or more critical points during execution. The three most common failure points are:

Here is a minimal example of how each layer should connect in a Node.js / Apollo Server setup:

// 1. Middleware: parse JWT and attach user to context
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => {
    const token = req.headers.authorization?.replace("Bearer ", "");
    if (!token) return { user: null };
    try {
      const user = jwt.verify(token, process.env.JWT_SECRET);
      return { user };
    } catch {
      return { user: null }; // expired or malformed
    }
  },
});

// 2. Resolver: check context before returning data
const resolvers = {
  Query: {
    adminUsers: (_, __, context) => {
      if (!context.user) {
        throw new GraphQLError("Not authenticated", {
          extensions: { code: "UNAUTHENTICATED", http: { status: 401 } },
        });
      }
      if (!context.user.roles.includes("ADMIN")) {
        throw new GraphQLError("Not authorised", {
          extensions: { code: "FORBIDDEN", http: { status: 403 } },
        });
      }
      return UserService.getAllUsers();
    },
  },
};

The OWASP framework specifically calls out Broken Object Level Authorization (BOLA) as a primary API risk. GraphQL is particularly susceptible because object-relationship traversal can reach unauthorised data through multiple indirect paths — none of which a single gateway check will catch.

Common authorisation implementation flaws

The most frequent mistakes teams make — and how to fix them:

Field-level permissions are the most commonly skipped layer: developers secure object access but forget to restrict individual sensitive fields within an authorised object — SSNs, internal notes, payment data. Schema directives help here but must be applied consistently; a single unguarded field in a related resolver undoes the rest.

The problem with default GraphQL behaviours

Most GraphQL libraries ship with defaults optimised for development convenience, not production security:

• Introspection enabled — gives any client a full map of your schema, types, and relationships.
• Detailed error messages — reveal database structure, field names, and internal logic in stack traces.
• No query depth or complexity limits — allows resource-exhaustion attacks through deeply nested queries.
• Permissive CORS — allows cross-origin requests from any domain.

Audit all four of these before going to production. Disabling introspection alone removes the easiest reconnaissance step from any attacker’s playbook.

How attackers exploit authorisation gaps

Security researchers have documented a consistent attack progression across GraphQL implementations in different industries:

Data exfiltration via relationship traversal is the most common technique: an attacker starts with a legitimately accessible object (say, their own Order) and traverses nested relationships to reach other customers’ data, payment methods, or admin records — exploiting gaps in resolver-level authorisation at each level.

Impact of successful exploits

Real-world breach patterns

A recurring pattern in reported GraphQL breaches: authenticated customers could access other customers’ order histories and payment methods through crafted queries that bypassed field-level authorisation checks on nested resolvers. The top-level Order resolver was secured; the nested paymentMethod and shippingAddress resolvers were not.

In healthcare GraphQL APIs, authorisation failures on nested medical-record relationships allowed users to traverse from their own patient record to unrelated providers’ records — exposing data across patients who shared a care pathway. These incidents consistently share one root cause: missing resolver-level checks on nested objects.

Detecting and testing for authorisation vulnerabilities

Testing GraphQL authorisation requires a different approach from REST. The single endpoint means you cannot rely on URL-based access controls — you must probe field-level and relationship-level permissions explicitly.

Tools for security testing

Automated tools are useful for schema analysis and known vulnerability patterns, but manual testing remains essential for business-logic authorisation flaws — for example, verifying that a user cannot access another user’s resources by changing an ID in a query.

Analysing your schema for security gaps

Schema analysis is the fastest way to prioritise where to focus authorisation testing. Look for:

• Fields with sensitive names (ssn, password, internalNote, paymentMethod) that lack directives or resolver-level checks
• Relationship fields that connect user-owned objects to objects owned by others
• Mutations that modify data without explicit role or ownership validation
• Queries that accept ID arguments — a classic BOLA vector

Implementing robust authorisation in GraphQL

Secure GraphQL authorisation requires defence-in-depth: validating permissions at the middleware layer, within individual resolvers, and optionally at the schema level via directives. The most maintainable approach centralises your authorisation rules so they are auditable in one place.

Authentication establishes who the user is; authorisation determines what that user can do at each step of query execution. The two are distinct, and conflating them is the most common source of FORBIDDEN errors that appear only on specific nested fields after a user is already authenticated.

Best practices by authentication method

Using middleware and graphql-shield for authorisation

Middleware intercepts every request before resolvers execute, making it the right place to parse tokens, build the user context, and reject unauthenticated requests early — before they consume resources. But middleware alone cannot enforce field-level permissions. That is where graphql-shield comes in:

import { shield, rule, and } from "graphql-shield";

const isAuthenticated = rule({ cache: "contextual" })(
  async (parent, args, ctx) => ctx.user !== null || new Error("Not authenticated")
);

const isAdmin = rule({ cache: "contextual" })(
  async (parent, args, ctx) =>
    ctx.user?.roles.includes("ADMIN") || new Error("Admin access required")
);

export const permissions = shield({
  Query: {
    allUsers: and(isAuthenticated, isAdmin),
    myProfile: isAuthenticated,
  },
  Mutation: {
    deleteUser: and(isAuthenticated, isAdmin),
  },
  User: {
    paymentMethods: isAuthenticated,    // field-level rule
    internalNotes: isAdmin,             // admin-only field
  },
});

Benefits of this pattern:

Advanced authorisation patterns

As your application grows, simple role checks give way to more sophisticated access control models. Choose based on your complexity and performance requirements:

Directive-based access control is one of the cleanest options for teams who want security rules visible directly in the schema:

directive @auth(requires: Role = USER) on FIELD_DEFINITION

enum Role { ADMIN USER GUEST }

type Query {
  allUsers: [User]    @auth(requires: ADMIN)
  myProfile: User     @auth(requires: USER)
  publicInfo: Info    # no directive = public
}

type User {
  id: ID!
  email: String       @auth(requires: USER)
  internalNotes: String @auth(requires: ADMIN)
}

Reducing attack surface with non-variable queries

Query designs that rely on server-side context (the authenticated user’s identity from the token) rather than client-supplied parameters dramatically reduce the BOLA attack surface. Instead of query { user(id: "123") { ... } } — where a user can manipulate the ID — prefer query { me { ... } }, where the server resolves the identity from context.user.id. This eliminates the most common direct object reference vulnerability in GraphQL.

Continuous authorisation and monitoring

Implementing authorisation once is not enough. Credentials are revoked, roles change, and new fields are added to the schema. Continuous authorisation means your permission checks re-validate context on every request and your monitoring surfaces anomalies before they become breaches.

Runtime monitoring for GraphQL should track: repeated UNAUTHENTICATED errors from a single IP (credential stuffing), unusually deep or complex queries (reconnaissance or DoS), and successful queries that access sensitive fields from new geographic locations or unusual times.

Rate limiting and abuse prevention

Standard request-count rate limits do not adequately protect GraphQL: a single deeply nested query can consume 100× more resources than a simple one. Use query complexity scoring alongside request-count limits:

Critically, rate limiting must integrate with your authorisation layer: unauthenticated requests that repeatedly trigger UNAUTHENTICATED errors should be throttled aggressively to prevent credential brute-forcing.