Authentication

The default behavior of the gateway depends on whether any authentication is configured or not. When there isn't, the gateway will provide an anonymous token for each request.

On the other hand, if there is, whether it's an extension or the deprecated embedded jwt, the gateway will deny access if the user could not be authenticated.

This can be controlled with the following:

[authentication]
# If the client could not be authenticated
# Deny access
default = "deny"
# or grant an anonymous token
default = "anonymous"

The optional MCP endpoint is also exposed by the gateway, but it can have different authentication needs. For example, you might want to use a different authentication mechanism for the MCP endpoint than for the GraphQL API, or you may want to have some of your GraphQL API public, but your MCP endpoint entirely private. For these use cases, you can configure the authentication for each resource individually:

[authentication.protected_resources.graphql]
extensions = []
default = "anonymous" # superfluous here, it's the default with no extension

[authentication.protected_resources.mcp]
extensions = ["jwt"]
default = "deny" # matches the default when at least one extension is defined

[extensions.jwt]
version = "1"
config.url = "https://example.com/sso/jwks"

Authentication extensions are available in the Marketplace:

• JWT: Validates a JWT token

You can learn how authentication extensions work and build your own with this follow along tutorial: Customize your GraphQL Federation authentication and authorization with Grafbase Extensions.

A complete example can be found on GitHub and the Grafbase SDK is the extension reference.

The Grafbase Gateway has an embedded JWT authentication implementation, with the same configuration as the JWT extension.

[[authentication.providers]]

[authentication.providers.jwt]
name = "my-authenticator"

[authentication.providers.jwt.jwks]
url = "https://example.com/.well-known/jwks.json"
issuer = "example.com"
audience = "my-project"
poll_interval = 60

[authentication.providers.jwt.header]
name = "Authorization"
value_prefix = "Bearer "

• The name field specifies the name of the authenticator.
• The jwks section specifies the URL of the JWKS endpoint, the issuer, and the audience. The audience can be an array, in which case any audience in the JWT must match any of the audiences in the array. The poll_interval specifies how often the JWKS endpoint should be polled for updates.
• The header section specifies the header name and value prefix for the JWT token.

The poll_interval field is a duration.

Read more about JWT authentication.