Skip to content


broker is basebox' GraphQL HTTP(s) server. Your client sends GraphQL requests to the broker's /graphql endpoint, e.g.

The broker's tasks are:

  • Handle OpenID Connect
  • Authorize and authenticate GraphQL requests
  • Validate GraphQL requests
  • Host the BLL (Business Logic Layer, not part of the first BETA but coming soon)
  • Communicate with the dbproxy to resolve requests
  • Return GraphQL compliant JSON response

Running the broker

In production, the broker should be run as a system service; we will provide instructions on how to achieve this soon. For now, since basebox is not yet production ready, you run broker simply in a terminal.

Command Line Parameters

To see broker's command line arguments, call it with --help:

❯ ./broker --help

This is broker, basebox' universal high performance GraphQL server.

Usage: broker [OPTIONS]

  -c, --config-file <CONFIG_FILE>
          Path and file name of the configuration file

  -d, --dump-default-config
          Dump default config file to stdout and quit

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

So to run broker, you create the config file (see below) and start broker like so:

./broker -c /path/to/broker-config.toml

Example Configuration File

Most of broker's options are controlled by a TOML configuration file. You can get the default configuration file and use it as a starter for your own configuration by running broker with the -d switch; so to create a config file template, just run:

./broker -d > config.toml

This will create a file named config.toml in the current directory with the default configuration.

Here is the current version:

# log level; can be error, warn, info, debug, trace
log_level = "info"

# path and file name to GraphQL schema file
schema_file = "/path/to/schema.gql"
# allow introspection is off by default
allow_introspection = false

# host name or IP of basebox DB proxy
host = ""
port = 8081
# Whether to use http or https to connect to the proxy
tls = false

# Host name of the broker (GraphQL server)
host = ""

# Port number; default is 80 for http, 443 for https
port = 8080

# number of HTTP server threads to spawn; default is one per CPU core
# workers = 2

# Path and file name of TLS/SSL key file
# tls_key_file = "/path/to/key.pem"

# Path and file name of TLS certificate (chain) file
# tls_cert_file = "/path/to/cert.pem"

# `mode` can be either "access-token" or "client". In access-token mode, all clients sending
# GraphQL requests to basebox just pass an access token in the "Authorization" HTTP header.
# In client mode, basebox acts as the OpenID Connect client and requests ID and access tokens
# from the OpenID Connect server on behalf of the client.
# See
mode = "access-token"

# URL of IdP's discovery endpoint. If not set, the URL is made up by appending
# ".well-known/openid-configuration" to the `iss` field.
# discovery_url = ""

# URL of IdP's public keystore. If set, the discovery endpoint is not used at all.
# jwks_url = ""

# Access token validation:
# Contents of 'iss' field, usually the URL of the authentication realm
# iss = ""

# Contents of the 'aud' field for access tokens; for Keycloak, this defaults to 'account';
# for Auth0, this is the value of the Default Audience field in your Tenant settings.
# aud = "account"

# To use "client" mode, please see the docs:

More on the configuration options can be found in broker's reference.

Last update: 2023-11-06