Skip to main content
A data app can also fetch from third-party HTTP APIs — for example, your own product API, a payments provider, or a Google API like BigQuery’s REST endpoint. A project admin registers each API as an external connection (base URL, allowed methods, auth), and app builders link the connections they need. At runtime, requests go through a Lightdash-mediated proxy that injects credentials server-side, so secrets are never exposed to the app code or the browser. External connections are managed under Project Settings → Data app connections on the project. The proxy requires HTTPS and blocks private/internal addresses by default. Self-hosted instance operators can explicitly approve trusted internal destinations with APP_RUNTIME_EXTERNAL_CONNECTION_ALLOWED_PRIVATE_HOST_CIDRS. See private-network external connections for configuration and security boundaries. Chart Studio chart types link connections the same way, so a chart type can call an API or show images from a URL field.

​
Configuring a connection

A connection is scoped to a project and stores:
  • Name - a short, human-readable identifier the app uses to refer to the connection.
  • Base URL - the origin the app is allowed to reach. The proxy pins requests to this host; an app cannot redirect a fetch elsewhere.
  • Allowed methods - which of GET, POST, PUT, PATCH, DELETE the app can use. New connections default to GET only; broaden the set only for APIs that actually need writes.
  • Allowed paths - optional path prefixes that further restrict where under the base URL the app can call.
  • Auth - see Auth types below.
  • Custom headers - up to 20 static headers sent with every request, for APIs that expect a version or similar header. Header values are stored as plain configuration, so never put a secret here; credentials go in Auth. Credential and routing headers such as Authorization, X-Api-Key, Cookie, and Content-Type can’t be set this way.
  • Forward viewer identity - see Forwarding viewer identity below.
  • Who can link it - Admins only, or Data app and chart type builders so editors can attach the connection from a data app or Chart Studio.
  • Public images - the Allow public images in linked apps toggle lets linked apps and chart types load images straight from the origin, in <img> tags or CSS. Off by default; enable it only for trusted public image or tile hosts.
  • Instructions - see Usage instructions below.
  • Size limits - under Advanced settings, Response max bytes caps what the API can send back (default 1 MiB, up to 25 MiB). Once POST is allowed, Request max bytes caps the query string and JSON body an app can send (default 256 KiB, up to 10 MiB). A request or response over its limit fails with an error rather than being cut short, so raise the limit or narrow the request.
Configuring a connection (create, edit, delete) requires the admin-only manage:ExternalConnection scope. Viewing the list — so an app builder can pick a connection to link — is available to Interactive Viewer and above, and only shows connections set to Data app and chart type builders; admins see all of them. Who can link it controls who can attach a connection to an app, not who can use it afterwards. Once a connection is linked, anyone who can view the app, including embedded viewers, can make requests through it with the connection’s credential. To limit what they can reach, narrow the connection’s Allowed methods and Allowed paths, or turn on Forward viewer identity so the external service applies its own per-user rules.

​
Auth types

Pick the auth method that matches the target API. The secret is encrypted at rest and never returned to the client after it’s saved — the proxy decrypts it server-side only when actually making a request.
  • None - no credentials are injected. Use this for public endpoints.
  • API key - a secret injected either as an HTTP header or a query parameter. You provide the parameter name (e.g. X-Api-Key) and the location (header or query). The secret is sent exactly as entered, with no prefix, so include any scheme the API expects. To call the Lightdash API with a personal access token, use the header Authorization and the value ApiKey <token>.
  • Bearer token - a secret injected as Authorization: Bearer <token>.
  • Google service account - paste a Google service-account key file (the full JSON) and enter one or more OAuth scopes (e.g. https://www.googleapis.com/auth/bigquery). At request time, the proxy exchanges the key file and scopes for a short-lived Google access token and injects it as Authorization: Bearer <token>. For example, to read Google Sheets, set the base URL to https://sheets.googleapis.com, add the scope https://www.googleapis.com/auth/spreadsheets.readonly, and share each sheet with the service account’s email address (client_email in the key file).
  • OAuth 2.0 client credentials - provide a token URL, client ID, client secret, and optional scopes. Choose Authorization header or Request body to match the OAuth server’s client authentication requirements. The proxy obtains and caches an access token server-side, then sends it to the API as a bearer token. A private token endpoint needs its own operator-approved hostname and CIDR when it differs from the API host.
In every case the injected credential is added by the proxy at request time; the generated app only ever sees the connection alias and the response body.

​
Forwarding viewer identity

Enable Forward viewer identity below Custom headers when adding or editing a connection to let the external service apply per-user access rules. This setting is off by default for each connection. When enabled, Lightdash adds these headers alongside the connection’s credentials: Lightdash sets these headers server-side; app code cannot override them, and their names are reserved in custom and API-key headers. Missing identity attributes are omitted. Connection tests use the testing administrator’s identity and omit the app ID. The headers are unsigned. Enable forwarding only for services you trust with viewer information. Before using the headers for authorization, the receiving service must authenticate Lightdash through the connection credentials or a trusted network boundary.

​
Testing a connection

The add-connection wizard and the Edit modal both include a Test step you can use to verify the connection before an app depends on it. The test runs through the exact same proxy path as a real app fetch (including host pinning and credential injection), so a passing test reflects real runtime behavior. On the Test step you can:
  • Pick any method the connection allows (the dropdown is restricted to your allowed-methods list).
  • Enter a path relative to the base URL.
  • Provide a JSON request body for non-GET methods.
The response comes back with its HTTP status, content type, and body (truncated if oversized). From a passing test you can optionally Save as sample — a redacted, size-capped snapshot of the response that’s passed into the app-build sandbox so the generator knows the API’s response shape.

​
Usage instructions

Each connection has an optional freeform Instructions field (markdown, up to 10,000 characters) where an admin can write notes on how apps should use the API — auth quirks, pagination style, which endpoints matter, rate-limit hints, response caveats. These instructions are passed into the app-build sandbox alongside the technical spec, so the generator uses the same guidance you’d give a human integrator. For example, on a fictional ecom orders_api you might write: