Which directives are available for authorization?

@authenticated requires any valid authentication. @requiresScopes requires specific OAuth scopes. Both are evaluated at the router before query execution.

How does @requiresScopes express AND vs. OR logic?

The scopes argument takes a nested array. Each inner array is an AND condition: all scopes in that array must be present. Multiple inner arrays are OR conditions: any one of them satisfies the requirement. For example, [["admin", "write"], ["superuser"]] means ("admin" AND "write") OR "superuser".

Do directives in subgraphs automatically apply to the federated schema?

Yes. Directives declared in a subgraph propagate to the federated schema during composition. A directive on a field in one subgraph enforces the requirement across the entire federated graph, regardless of which subgraph resolves the field.

What router version is required?

Router version 0.60.0 or higher is required for authorization directive support. Control Plane version 0.58.0 or higher and wgc CLI version 0.39.0 or higher are also required. JWT Authentication must be configured on the router.

What happens when a nullable field fails authorization?

The nullable field returns null, and an authorization error appears in the errors array of the response. A non-nullable field that fails authorization causes the entire response data to return null, even when other selected fields required no authorization.

Can I apply directives to interfaces and enums?

Yes. @authenticated and @requiresScopes can be applied at the field level, object type level, interface level, enum level, or scalar level. A directive on a type protects every field that returns that type.

Authorization Directives for GraphQL | Cosmo by WunderGraph

The problem

Authorization scattered across resolvers is a liability

In a federated graph, each team implements access control independently. The result is inconsistent enforcement and no visible record of what each field requires.

Authorization logic lives in resolver code

Each resolver that handles sensitive data contains its own access checks. There is no single place to see what each field requires. Auditing means reading every resolver.

Enforcement is inconsistent across subgraphs

In a federated graph, each subgraph team implements authorization independently. One subgraph enforces scope checks; another does not. The gaps are invisible until something is accessed that should not be.

Access requirements are not visible in the schema

Developers reading the schema cannot tell which fields require authentication or which scopes are needed. That context exists only in the implementation — not in the API contract.

Our solution

The schema documents and enforces access requirements

Authorization directives embed access requirements directly in the GraphQL schema. The router evaluates them before execution — no code changes needed in resolvers.

From schema declaration to enforcement

Declare @authenticated on any field, object, interface, enum, or scalar that requires authentication.
Declare @requiresScopes with a nested array of scope requirements. Inner arrays are AND conditions; outer arrays are OR conditions.
Directives declared in a subgraph schema propagate automatically to the federated schema during composition.
At request time, the router evaluates directives before query execution — no resolver code runs for unauthorized fields.
Nullable fields return partial data with authorization errors. If a non-nullable field fails authorization, the entire response data returns null.
@requiresScopes error messages specify the required and actual scopes, giving clients actionable context. @authenticated errors state the reason: not authenticated.

JWT Authentication must be configured. Router 0.60.0+, Control Plane 0.58.0+.

Authorization directives

Before & After

Before Cosmo	With Cosmo
Authorization checks scattered across resolver functions	Declarative directives in the schema
No single source of truth for access requirements	Schema documents and enforces requirements simultaneously
Each subgraph implements authorization independently	Directives propagate automatically to the federated graph
Custom code for every protected field	@authenticated or @requiresScopes in one line

Scope logic

AND / OR with nested arrays

@requiresScopes(scopes: [["hr:read"]])
Requires "hr:read".

@requiresScopes(scopes: [["admin", "write"]])
Requires "admin" AND "write".

@requiresScopes(scopes: [["management:read"], ["hr:admin"]])
Requires "management:read" OR "hr:admin".

Inner arrays: AND conditions. Outer arrays: OR conditions.

How authorization directives work in Cosmo

01

Schema is the source of truth.

Declare

Add @authenticated or @requiresScopes to any field, type, interface, enum, or scalar in a subgraph schema. @requiresScopes uses a nested array: inner arrays are AND, outer arrays are OR. Example: [["hr:read"]] requires "hr:read". [["admin", "write"], ["superuser"]] requires ("admin" AND "write") OR "superuser".

02

Cross-subgraph propagation, automatic.

Propagate

During federation composition, directives declared in any subgraph propagate to the federated schema. Directives on types protect all fields returning that type. @authenticated on an interface field protects only that interface field — it does not protect the corresponding fields on implementing types.

03

Evaluated at the router, pre-execution.

Evaluate

The router evaluates directives before query execution. JWT claims must be present and validated first. @authenticated checks for any valid authentication. @requiresScopes checks scope claims against the configured AND/OR logic. Requires Router 0.60.0+ and Control Plane 0.58.0+.

04

Partial data for nullable fields.

Respond

For nullable fields, the router returns partial data with authorization errors in the errors array. If a non-nullable field fails authorization, the entire response data returns null. @requiresScopes error messages include the required and actual scopes.

Authorization controls

Field-level control, from simple to complex

Protect individual fields or entire types with a single directive.

Apply at any level

Declare directives on fields, object types, interfaces, enums, or scalars. A directive on a type protects every field that returns that type. A directive on an interface field protects that interface field only, not the fields of implementing types.

Cross-subgraph propagation

Directives in any subgraph schema propagate to the federated graph during composition. A directive declared in the pricing subgraph enforces the requirement regardless of which subgraph resolves the field.

Partial data for nullable fields

When authorization fails on a nullable field, the field returns null and an error appears in the errors array. When a non-nullable field fails authorization, the entire response data returns null.

Clear error messages

@requiresScopes errors include the required and actual scopes from the token. @authenticated errors state the reason: not authenticated. Clients receive actionable information about what permissions they need.

Add field-level authorization to your schema

Declare @authenticated or @requiresScopes. The router enforces them. No resolver changes required.

Start Free Read the Docs

Enforce field-level permissions from the schema itself