Skip to content
API Design Learn/GraphQL Real-Time & Security
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Field-Level Authorization

4 min read

You'll learn to

  • -Explain why a single check at the top of a GraphQL query cannot protect fields of different sensitivity
  • -Enforce rules per field, in the resolver or declared with an @auth directive
  • -Choose between null, a field error or an absent field, and read a partial response

In REST, authorization is usually checked once per endpoint: can this caller hit GET /users/42 at all? GraphQL breaks that habit. One query can touch dozens of fields across many types, and different fields on the same type can legitimately need different rules for the same caller. A resolver is the function that produces the value of one field.

An Analogy: The Hotel Key Card

A hotel key card does not just open "the hotel". It opens your room, the gym and the lift to your floor, and it does not open the staff office. Each door checks the card on its own. Field-level authorization is the same: every sensitive field is a door that checks the caller.

Why Endpoint-Level Auth Isn't Enough

One query, two fields with different sensitivity
query {
  user(id: "42") {
    name        # public - anyone can see this
    email       # only the user themselves, or an admin
    ssn         # only an admin, and only with a specific audit-logged reason
  }
}

A single check of "can this caller run the user query at all?" cannot say that name, email and ssn on the same User need three different rules for the same caller. That precision has to live with each field.

Declaring It in the Schema: the @auth Directive

A directive is an annotation on a schema element, starting with @, that a framework acts on. Writing the rule as an @auth directive on the field makes the authorization surface reviewable at a glance. Anyone reading the schema can see which fields are gated and by what rule. The framework runs the check consistently before each field's resolver, rather than relying on every author to remember to add it by hand.

The same rule, declared on the field instead of hidden inside resolver code
type User {
  name: String!
  email: String! @auth(requires: OWNER_OR_ADMIN)
  ssn: String! @auth(requires: ADMIN)
}

The demo applies those three rules. It asks four questions of the same data: a stranger asking about Ada, Ada asking about herself, an admin asking about Grace, who genuinely has no SSN, and a stranger asking about the same field of Grace. Watch what each response says about the ssn value and its error.

Press Run: the same fields come back differently for different callers

The Three Ways to Handle an Unauthorized Field

  • -Return null: the field exists for everyone but resolves to null for an unauthorized caller. Simple, but it mixes up "you cannot see this" with "this is genuinely empty".
  • -Raise a field-level error: GraphQL allows partial responses, so other fields in the query still succeed while one field reports an error. That is an explicit, unambiguous signal for that field.
  • -Leave the field out of the schema for this caller: the strictest option, for when even the field's existence should not be discoverable.

A field-level error is usually clearest for truly sensitive fields. In the demo, the stranger's ssn is null with an error attached, while Grace's ssn is also null but with no error. The null alone could not tell you which case you were in.

Because of partial responses, a query can return HTTP 200 with some fields filled and others reporting errors in the same response. Client code must check per-field errors and not assume that a 200 means everything it asked for came back.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Permission Matrix in the API Design Lab's GraphQL Mastery act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!