BroadSQL BroadSQL Downloads
On this page
Documentation / API Client: Parameters, variables and authentication

Parameters, variables and authentication

A request is rarely fixed: an id, a country, a token, a base URL change from one call or one environment to the next. This page explains where each value comes from: ${name} variables stored with the API, :name placeholders resolved at run time, session values set with VAR, operating system variables, and the credentials of each authentication type.

Authentication

Whatever authentication the Bruno collection defines is imported and works automatically; nothing needs to be reconfigured in BroadSQL. Authentication can be set on the whole API, on a folder (inherited by every endpoint inside it), or on one endpoint specifically; a more specific setting always overrides a less specific one, and an endpoint explicitly configured with no authentication is never given one it didn't ask for.

Supported and executable in this release:

  • No authentication
  • HTTP Basic
  • Static Bearer token
  • API key, in a header or a query parameter
  • OAuth2 Client Credentials (the access token is fetched automatically, cached in memory, and refreshed before it expires, never written to disk)

A credential that references an environment variable (the normal Bruno pattern, e.g. a Bearer token set to a variable) resolves against whichever environment you selected; switching environment switches credentials with it.

Other authentication schemes a Bruno collection might use (Digest, NTLM, OAuth1, AWS Signature, OAuth2 Authorization Code or Password grants) are imported and preserved, but this release cannot execute them: attempting to run such an endpoint is refused, naming the original authentication type, rather than silently sending the request unauthenticated.

Variables

A variable is referenced inside a URL, header value, query/path parameter value, request body, or authentication property with:

${variableName}

for example ${baseUrl}/users?key=${KEY}. This is BroadSQL's canonical variable syntax: it is what CONFIG API, generated examples, and every command in this document use.

Bruno's own {{variableName}} mustache syntax is also accepted, for interoperability with content imported from, or destined for, Bruno collections:

{{variableName}}

A single URL, header, or parameter may freely mix both forms; both are resolved identically, and either fails the same way if the variable cannot be resolved: execution stops before any network request is made, naming exactly which variable is missing. New requests configured by hand in BroadSQL should use ${variableName}; {{variableName}} exists so a Bruno collection's own syntax keeps working end to end (import, edit, execute, export back to Bruno) without a lossy conversion step, not as a second style to choose between when authoring something new.

Variable names are matched case-sensitively. A variable saved as KEY is referenced as ${KEY}, not ${key}: a differently-cased reference is treated as a different, unresolved name.

${variableName}/{{variableName}} is one of four distinct placeholder forms BroadSQL's API client uses, each with its own syntax and its own resolution rule: the sections below cover the other three.

Runtime placeholders (:name)

A :name segment in a RUN URL, whether a path segment (/users/:id) or a query value (?limit=:limit), is a runtime placeholder, resolved fresh for that one RUN call, not a stored ${variableName} reference. It is looked up case-insensitively, in this order, stopping at the first match:

session VAR
    -> current API environment variable
    -> this endpoint's own persisted CONFIG API value
    -> this endpoint's configured default
    -> error: missing required parameter (if none of the above resolves it)

A literal value in the URL (/users/42) is used and validated as-is; :name placeholders and literal values can appear side by side in the same URL. See VAR below for setting the first (session) step of this chain, and Scope and precedence for how the second (API environment) step relates to ${variableName} templating's own, separate precedence chain.

Operating system environment variables (${ENV:NAME})

${ENV:NAME}

reads an operating-system environment variable at the moment the command runs: a different namespace from ${variableName} (no ENV: prefix), used only in a RUN URL or a VAR value, never inside a stored endpoint definition. An undefined OS environment variable fails explicitly, exactly like an undefined ${variableName}; it is never silently substituted with an empty string.

RUN /api/customer/${ENV:CUSTOMER_ID};
VAR ID=${ENV:CUSTOMER_ID};

Session variables (VAR)

VAR <name>=<value-expression>;

sets a temporary, session-only variable: the first, most specific step of the :name resolution chain above. <value-expression> may reference ${ENV:NAME} (resolved once, at assignment time); a value containing spaces must be double-quoted:

VAR ID=123;
VAR COUNTRY=FR;
VAR NAME="John Doe";
VAR ID=${ENV:CUSTOMER_ID};

VAR <name>=<value> PERSIST; does something different: instead of a session variable, it writes the value into the current API environment's own variable set (the same store CONFIG API's Environments tab edits, see Environments) by case-insensitive name, leaving every other field of an existing row (enabled state, secret flag, and so on) untouched. It then clears any session VAR of the same name, so the newly persisted environment value is what every subsequent command sees immediately, through the normal resolution chain above, with no stale session override left shadowing it. PERSIST requires an active CONNECT API session (there is otherwise no "current environment" to persist into); plain VAR name=value;, without PERSIST, never touches the database and works with or without a session:

CONNECT API MYAPI:Development;
VAR ID=123 PERSIST;

Scope and precedence

${variableName}/{{variableName}} templating (the form used inside a stored endpoint's own URL, headers, parameter values, request body, and authentication properties) has its own, separate scope chain from :name's runtime resolution above. A variable may be defined at several levels; the most specific one that defines a given name wins:

API variables
    -> environment variables (the selected environment only)
    -> folder variables (root to leaf, along the endpoint's folder chain)
    -> endpoint variables

An API-level variable is the broadest scope: it is sometimes called a "global" variable for the API, since it applies regardless of which environment or folder the endpoint sits in. A variable defined again at a more specific scope (environment, then folder, then endpoint) simply shadows the same name at every broader scope; it does not need to be re-declared everywhere.

Headers and query/path parameters are not part of this variable-precedence chain: a header or parameter is resolved after variable substitution, in its own separate precedence (API default, then folder, then endpoint, then whatever authentication adds), unrelated to where the *variable values themselves* were defined. An enabled query/path parameter is resolved the same way any other ${variable} reference is; a disabled one is skipped entirely, see Query parameters and the URL.

A complete example

An API-level (global) variable:

KEY = DESK

An endpoint's query parameter:

key = ${KEY}

Executing that endpoint resolves the parameter to the variable's value:

...?key=DESK

Changing environment never changes this, unless an environment-level variable named KEY (which would override the API-level one for that environment) or a folder/endpoint-level one is also defined.

baseUrl

baseUrl is an ordinary environment-scope variable, not a separate mechanism: it is simply the variable name BroadSQL (and Bruno) use, by convention, for an environment's base server URL. Setting Base URL in the Environments tab of CONFIG API (see "Base URL" above) sets this variable; referencing ${baseUrl} (or {{baseUrl}}) inside an endpoint's URL resolves it exactly like any other variable. A manually-created endpoint that uses a bare relative path (/users, with no ${baseUrl} at all) has the environment's Base URL prefixed automatically instead; both styles resolve correctly.

Secrets

A variable marked secret (a token, a password, a client secret) is masked in every table BroadSQL shows, and is never printed by RUN, SHOW ENDPOINTS, SHOW ENDPOINT, or the CONNECT API confirmation message: only the API and environment names are shown there, never variable values. A secret is still fully usable in ${variable}/{{variable}} references; masking only affects display.

Example: supply a value for one session

CONNECT API ORDERS:Development;
VAR id=1042;
RUN /orders/:id;

:id is found in the session VAR first, so the request goes to /orders/1042. VAR id=1042 PERSIST; would store it in the Development environment instead.