v0.15.1 v0.17.5 v0.17.4 v0.17.3 v0.17.2 v0.17.1 v0.17.0 v0.16.0 v0.15.0 v0.14.0 v0.13.0 v0.12.2 v0.12.1 v0.12.0 v0.11.3 v0.11.2 v0.11.1 v0.11.0 v0.10.2 v0.10.1 master

Schema Directives

Using schema directives to implement permission checks
You are looking at the docs for an older version (v0.15.1). The latest version is v0.17.5.

Directives act a bit like annotations, decorators, or HTTP middleware. They give you a way to specify some behaviour based on a field or argument in a generic and reusable way. This can be really useful for cross-cutting concerns like permission checks which can be applied broadly across your API.

Note: The current directives implementation is still fairly limited, and is designed to cover the most common “field middleware” case.

Restricting access based on user role

For example, we might want to restrict which mutations or queries a client can make based on the authenticated user’s role:

type Mutation {
	deleteUser(userID: ID!): Bool @hasRole(role: ADMIN)

Declare it in the schema

Before we can use a directive we must declare it in the schema. Here’s how we would define the @hasRole directive:

directive @hasRole(role: Role!) on FIELD_DEFINITION

enum Role {

Next, run go generate and gqlgen will add the directive to the DirectiveRoot:

type DirectiveRoot struct {
	HasRole func(ctx context.Context, obj interface{}, next graphql.Resolver, role Role) (res interface{}, err error)

The arguments are:

Implement the directive

Now we must implement the directive. The directive function is assigned to the Config object before registering the GraphQL handler.

package main

func main() {
	c := generated.Config{ Resolvers: &resolvers{} }
	c.Directives.HasRole = func(ctx context.Context, obj interface{}, next graphql.Resolver, role Role) (interface{}, error) {
		if !getCurrentUser(ctx).HasRole(role) {
			// block calling the next resolver
			return nil, fmt.Errorf("Access denied")

		// or let it pass through
		return next(ctx)

	http.Handle("/query", handler.NewDefaultServer(generated.NewExecutableSchema(c), ))
	log.Fatal(http.ListenAndServe(":8081", nil))

That’s it! You can now apply the @hasRole directive to any mutation or query in your schema.