Skip to content

broker Reference

HTTP Endpoints

broker provides various HTTP endpoints (or paths) your client needs to call to handle authorization and GraphQL requests.


Method: POST

Handles GraphQL requests from authenticated clients.


Method: GET Query parameters: app-scheme (see below)

This is where your client starts the login process. Returns a 302 response with the URL of the OpenID Connect provider/server login form in the Location header field. If your client is not a browser, you must ensure that when calling the URL, you also pass all the URL's query parameters.

After the user submits his/her credentials to the login form, the IdP responds with a 302 redirect response to the clients OAuth2 callback; for more information, see our Authorization page.

If the user session is still valid, the IdP might not display the login form but immediately respond with a 302 response to the client's OAuth2 callback.


This path is configurable in the config file; see the login_path option in the auth section below.

Query Parameters


Optional; name of the application scheme to get a login URL for. You can define app schemes in the config file, see auth.app_schemes below.
If omitted, the redirect_url defined in section [auth] is used.


Method: POST

Accepts the query parameters passed to the client server's OAuth2 callback endpoint. If everything is all right, responds with a 200 code and a JSON payload containing user session information:

    "name":"Tester First",


The exact contents of the returned JSON object depend on the OpenID Connect provider you are using. The example above is what gets returned when using AUth0.
The token field however is always present, as this is the basebox session token; see below.

The client can now call the /graphql endpoint to send GraphQL requests. When doing so, the client must pass the session token in the Authorization header field as a bearer token:

Authorization: Beader <token>

JavaScript fetch API example:

fetch("https://basebox.tld/graphql", {
  "headers": {
    "Authorization": "Bearer 6aa1337f-595a-44b7-be6a-635582187bc6"


This path is configurable on the config file; see the openid_connect_path option in the auth section below.

Configuration File

The configuration file is in TOML syntax; it is very similar to good old INI files and organizes options in sections, denoted by square brackets.

Section generic


Type: String
Set broker's log level or verbosity; we recommend setting it to info. Possible values from least to most verbose are:
"error", "warn", "info", "debug", "trace"

Section graphql


Type: String
Path and filename to your project's GraphQL schema file.


Type: boolean
Set to either true or false. Turns GraphQL introspection on or off. Should be off for production!

Section server


Type: String
Host name or IP address of the network interface broker should listen on for requests. For production use, this should be set to the IP address of the host; use "" to listen on all available interfaces and "" to only accept local connections (for testing etc). If you set this to a hostname, broker will bind to the IP address returned from a DNS lookup. Example: ""


Type: Integer
Port number; default is 80 for http, 443 for https.
Example: 8080


Type: Integer
Number of HTTP server threads to spawn; default is one per CPU core.
Example: 2


Type: String
Path and file name of TLS/SSL key file.
Example: "/path/to/key.pem"


Type: String
Path and file name of TLS certificate (chain) file.
Example: "/path/to/cert.pem"


Type: Integer
Maximum allowed HTTP request size in bytes; default is 256k.
Example: 262144

Section proxy

This section defines how the broker should connect to dbproxy.


Type: String
host name or IP of basebox DB proxy.
Example: ""


Type: Integer
The TCP/IP port of dbproxy.
Example: 8081


Type: Boolean
Whether to use TLS to connect to dbproxy; set to true or false.
Example: false

Section auth


Type: String
Path and file name to a JSON Web Key Set (JWKS) file. This file contains the public keys that broker uses to verify access token signatures. This is an alternative to specifying the discovery_url and jwks_url fields below and can be used for environments that have no access to the internet. Example: "/path/to/jwks.json"


Type: String
Mode: access-token
URL of IdP's discovery endpoint; only needed if jwks_url is not set. If both fields are not set, the discovery URL is made up by appending ".well-known/openid-configuration" to the iss field.


Type: String
Mode: access-token
URL of IdP's public keyset; optional if discovery_url is set or can be derived from the iss field


Type: String
Mode: access-token
Issuer field, usually the URL of the IdP realm, e.g.


Type: String
Mode: access-token
Access token audience field

Section auth_management


Type: String
Name of the authentication provider to use for authentication management. Currently, only auth0 is supported.


Type: String
Domain of your Auth0 realm; example: ""


Type: String
Client ID of the machine-to-machine client that is allowed to get access tokens for the Management API.


Type: String
Client secret of the machine-to-machine client that is allowed to get access tokens for the Management API.