Directives

The Grafbase schema is built up of many types, fields, scalars, and directives. The combination of all these combined generate a GraphQL API deployed to the edge.

These directives can be applied at the schema level.

Use the @auth directive to configure providers, rules, and permitted operations.

Configure provider types such as OIDC that work with Grafbase to authenticate and authorize user requests.

OpenID Connect

schema
  @auth(
    providers: [{ type: oidc, issuer: "{{ env.ISSUER_URL }}" }]
    rules: [{ allow: private }]
  ) {
  query: Query
}

You must send OIDC (JWT) tokens using the authorization header.

The issuer URL must adhere to the OpenID Connect Discovery spec. We append /.well-known/openid-configuration to the URL to locate the OpenID configuration.

We recommended that you use an environment variable for the issuer value as shown in the previous example.

All rules are global. They apply to all queries and mutations, or permitted operations. We support the following strategies to control access to data:

  • Public/anonymous — Allow access with any valid API key
  • Signed-in user — Allow access to any signed-in user
  • User group-based — Allow acces to users of a group
schema @auth(rules: [{ allow: anonymous }]) {
  query: Query
}

We recommended that you use an environment variable for the issuer value as shown in the previous schema example.

Learn more about using Clerk as your Identity Provider.

You can restrict access to specific operations using rules.

You can set the following rules when using signed-in or group based authorization:

schema
  @auth(
    providers: [{ type: oidc, issuer: "{{ env.ISSUER_URL }}" }]
    rules: [{ allow: private, operations: ["get"] }]
  ) {
  query: Query
}

You can also set separate rules for operations.

The following authorization enable:

  • Signed-in users to perform read operations
  • Users of the moderator group to perform update operations
  • Users of the admin group to perform all operations
schema
  @auth(
    providers: [{ type: oidc, issuer: "{{ env.ISSUER_URL }}" }]
    rules: [
      { allow: private, operations: ["read"] }
      { allow: groups, groups: ["moderator"], operations: ["update"] }
      { allow: groups, groups: ["admin"] }
    ]
  ) {
  query: Query
}

These directives can be applied at the type level.

This directive instructs Grafbase to create an entry in the database for objects of the type.

The @model directive tells Grafbase that it is database model, and to generate queries and mutations for that type.

type Post @model {
  id: ID!
  title: String
}

You can mark fields as non-nullable, and opt-in to more advanced validations with custom scalars.

These directives can be applied at the field level.

The @unique directive tells Grafbase that this value must be unique (and case-sensitive) within the collection.

type User @model {
  id: ID!
  email: String! @unique
}