How do @authenticated and @requiresScopes work?

@authenticated requires valid authentication. @requiresScopes requires specific JWT scopes and supports AND/OR logic. Both are evaluated at the router before protected subgraph requests are made. JWT provider configuration is required on the router.

Can multiple subgraphs resolve the same field?

Yes. Mark the field with @shareable in all subgraphs that can resolve it. The query planner chooses the optimal subgraph based on the query plan.

What is @openfed__subscriptionFilter?

@openfed__subscriptionFilter is a Cosmo-specific directive for subscription event filtering. It requires an event-driven federation setup.

Where can I see the full list of supported directives?

See the Federation directives index and the Federation compatibility matrix in the Cosmo docs for supported directives and compatibility details.

GraphQL Federation Directives | Cosmo by WunderGraph

The problem

Without full directive support, federation breaks down

Federated GraphQL architectures need a way to express entity relationships, field dependencies, cross-subgraph sharing, and access control. Without comprehensive directive support, teams build workarounds or get blocked entirely.

No directive support means workarounds everywhere

Without @key, @external, @requires, and @provides, teams cannot cleanly express entity relationships and field dependencies across subgraphs. The result is workaround logic or blocked federation patterns.

Authorization requires custom code in every subgraph

Without declarative auth directives, teams write custom authorization code in each subgraph, making access control harder to implement consistently.

Field sharing and subscription filtering have no standard

Without @shareable, teams cannot use the standard field-sharing pattern for fields resolved by multiple subgraphs. Without subscription filter support, teams lack directive-based event filtering for subscriptions.

Our solution

Full directive coverage, from entity resolution to authorization

Cosmo supports federation directives for core federation, field sharing, visibility control, authorization, and subscription filtering. Directives are processed across schema composition and query planning, with authorization directives evaluated at the router before subgraph requests.

How it all fits together

Core federation directives (@key, @external, @requires, @provides, @extends) express entity relationships and field dependencies across subgraphs.
@shareable enables multi-subgraph field resolution. @override supports migrating field ownership between subgraphs.
@authenticated and @requiresScopes enforce access control at the router level. Requests that fail the required authorization checks are rejected before protected subgraph requests are made.
@inaccessible hides fields from the client schema. @tag attaches metadata for contracts and tooling.
Cosmo-specific extensions include @openfed__subscriptionFilter, @openfed__configureDescription, and @semanticNonNull.

Directive validation happens during composition. Authorization checks are evaluated at the router before protected subgraph requests are made.

Federation directives

Before & After

Before Cosmo	With Cosmo
Limited directive support	Full v1 and v2 directive compatibility
Custom authorization middleware per subgraph	Declarative `@authenticated` and `@requiresScopes`
Complex field sharing logic	Simple @shareable directive
No subscription filtering	`@openfed__subscriptionFilter` for subscription event filtering

Directive categories

Five directive groups

Core federation — @key, @external, @requires, @provides, @extends
Field sharing — @shareable, @override
Visibility control — @inaccessible, @tag
Authorization — @authenticated, @requiresScopes
Cosmo extensions — @openfed__subscriptionFilter, @openfed__configureDescription, @semanticNonNull

Key benefits

Complete Federation directive support

Full Federation v1 and v2 directive support plus Cosmo-specific extensions. Available on Free, Pro, and Enterprise.

Complete federation support

Cosmo supports all Apollo Federation v1 and v2 directives, including @key, @external, @requires, @provides, @extends, @shareable, @inaccessible, @override, @interfaceObject, and @tag.

Declarative authorization at the router

@authenticated and @requiresScopes enforce authorization at the router. Requests that fail the required authentication or scope checks are rejected before protected subgraph requests are made. Requires JWT provider configuration on the router.

Cross-subgraph field resolution

@shareable enables the same field to be resolved from multiple subgraphs. The query planner chooses the optimal subgraph based on the query plan.

Interface entity patterns

Interfaces can use @key(fields: "id"). Subgraphs that contribute fields to implementing types use @interfaceObject to add fields to all implementations.

Cosmo-specific extensions

@openfed__subscriptionFilter supports subscription event filtering. @openfed__configureDescription controls description propagation, and @semanticNonNull indicates semantic non-nullability.

How federation directives work

01

JWT config for auth directives.

Declare directives in subgraph schemas

Each subgraph declares the directives it uses, such as @key for entity resolution, @authenticated for protected fields, and @shareable for shared fields. Authorization directives require JWT provider configuration on the router.

02

Catch incompatibilities at compose time.

Composition validates directive usage

During schema composition, Cosmo validates directive usage across subgraphs so incompatible directive declarations can be caught before producing the composed schema.

03

@requires declares cross-subgraph deps.

Query planning uses field directives

Field-level directives such as @shareable, @provides, and @requires influence query planning decisions. @provides indicates conditionally available fields, and @requires declares field dependencies from other subgraphs.

04

Rejected at the router.

Router evaluates authorization directives

@authenticated and @requiresScopes are evaluated at the router before protected subgraph requests are made. Requests that fail the required authentication or scope checks are rejected at the router.

Need version details? Check the Federation compatibility matrix for directive support.

Use cases

Common directive patterns

Declarative authentication

@authenticated

Fields or types annotated with @authenticated require valid authentication. The router validates authentication before protected subgraph requests are made. Unauthenticated requests receive authorization errors.

Scope-based authorization

@requiresScopes

Fields annotated with @requiresScopes(scopes: [["read:users"], ["admin"]]) require specific JWT scopes and support AND/OR logic. The router validates that the request JWT contains the required scopes before allowing access.

Cross-subgraph field resolution

@shareable

A field marked @shareable in all subgraphs that can resolve it can be resolved from multiple subgraphs. The query planner chooses the optimal subgraph based on the query plan.

Entity interface patterns

@interfaceObject

Interfaces can be declared with @key(fields: "id"). Subgraphs that contribute fields to implementing types use @interfaceObject to add fields to all implementations.

When to use federation directives

When to use

You need entity resolution, field dependencies, or cross-subgraph field sharing in a federated graph.
You want declarative authentication or scope-based authorization without custom authorization code in every subgraph.
You are building subscription-based features and need @openfed__subscriptionFilter for event filtering.

Requirements & limitations

Authorization directives (@authenticated and @requiresScopes) require JWT provider configuration on the router.
Subscription filtering (@openfed__subscriptionFilter) requires an event-driven federation setup.

Build sophisticated federation patterns with directive support

Full v1 and v2 directive support, declarative authorization, and subscription filtering. Available on Free, Pro, and Enterprise.

Start Free See the docs

Ready to go deeper?

Explore the federation directives index, compatibility matrix, and per-directive guides for @shareable, @authenticated, and @requiresScopes.

Directives index →Compatibility matrix →

Complete directive support for sophisticated federation patterns

Without full directive support, federation breaks down

No directive support means workarounds everywhere

Authorization requires custom code in every subgraph

Field sharing and subscription filtering have no standard

Full directive coverage, from entity resolution to authorization

How it all fits together

Before & After

Five directive groups

Complete Federation directive support

Complete federation support

Declarative authorization at the router

Cross-subgraph field resolution

Interface entity patterns

Cosmo-specific extensions

How federation directives work

Declare directives in subgraph schemas

Composition validates directive usage

Query planning uses field directives

Router evaluates authorization directives

Common directive patterns

Declarative authentication

Scope-based authorization

Cross-subgraph field resolution

Entity interface patterns

When to use federation directives

When to use

Requirements & limitations

Build sophisticated federation patterns with directive support

Ready to go deeper?

GraphQL federation directives