Build your own integration
Integrations
Greenlight does not require a vendor-specific integration plugin for every upstream. Any HTTP service can be registered through the dashboard. IT supplies a base URL and an auth profile; the data broker handles the rest.
This page covers the conceptual flow. The step-by-step admin instructions live in Manage integrations.
What you need
- An HTTPS base URL for the upstream service.
- An authentication scheme — bearer token, basic auth, OAuth client credentials, OAuth token exchange, or a session header the broker should pass through.
- An idea of which apps will use it, since granting is per-app.
The auth profiles
Greenlight supports five auth profiles out of the box. Most custom integrations use one of the first three.
| Profile | When to pick it |
|---|---|
bearer | The upstream takes a static or rotated bearer token in Authorization |
basic | The upstream uses HTTP basic with a username and password |
oauth2_client_credentials | The upstream issues a token via the standard client-credentials grant |
oauth2_token_exchange | The upstream wants the end user’s identity via RFC 8693 |
header_passthrough | The upstream expects a header the platform supplies (used for opaque webhook signing, custom SaaS auth) |
Picking the right profile is usually a 30-second read of the upstream’s API documentation.
What an app sees
Once IT registers the integration as, say, myservice, the app reaches it through the proxy URL with the integration name as the first path segment:
await fetch( `${process.env.GREENLIGHT_PROXY_URL}/myservice/v1/widgets`, { method: 'GET' });The broker rewrites the path against the registered base URL and substitutes the credential. The app’s code stays portable — it depends on the proxy URL, not on the upstream’s hostname.
What gets audited
Every call through a custom integration is audited identically to a built-in integration:
- The bound user.
- The app id.
- The integration name and the upstream URL.
- The HTTP method and response code.
- The end-to-end latency.
The audit record does not include request bodies by default. Sensitive-field redaction is configurable per integration if a request body is genuinely needed in the log.
Versioning the integration
Greenlight does not version integration definitions. If you change the base URL, the auth profile, or the credential, the change takes effect on the next call. Apps that depend on a breaking change in the upstream see the same kind of breakage they would see directly — the broker is a pass-through for semantics, not a compatibility layer.