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.

​
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.
  • Instructions - see Usage instructions below.
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.

​
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).
  • 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>.
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.

​
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: 
- Paginate with `?page=` and `?per_page=` (max 100). The `Link` header contains the next-page URL.
- Timestamps are returned in the store's local time, not UTC. The store timezone is in `GET /store`.
- `/orders` returns open orders only unless `state=all` is passed.
- Rate limit: 60 req/min per IP.