Client-credentials integrations

Integrations

A client-credentials integration is the machine-to-machine OAuth kind. Instead of a static key, IT registers the upstream’s token endpoint, the OAuth client id and secret, and the scopes the app needs. Greenlight exchanges the client id and secret for a short-lived access token, caches it, refreshes it before it expires, and the data broker attaches it on every call.

Like a service account, the upstream sees one org-level identity — but the credential on the wire is a freshly minted, expiring bearer token, not a long-lived key. Per-end-user attribution lives in Greenlight’s audit log, not in the upstream system.

When to use this kind

Choose client credentials when the upstream’s own auth is “exchange a client id and secret for a token,” rather than a static key or a per-user login. This is the common shape for enterprise data feeds and platform APIs — Bloomberg Data License, Refinitiv / LSEG, FactSet, and many enterprise SaaS that issue short-lived OAuth tokens.

• Use service account instead when the upstream takes a single static key, header, or basic-auth credential.
• Use user-passthrough instead when the upstream must see the actual end user and enforce that user’s own permissions.

How the auth mode is set

A client-credentials integration uses the client credentials auth mode — see Data brokering for how the auth mode decides credential delivery across all three kinds. At registration IT provides:

• the token endpoint the OAuth exchange posts to,
• the scopes to request, and
• the client id and secret, which Greenlight stores in your vault and never exposes to apps.

Greenlight runs the token exchange on the control plane, caches the access token, and re-mints it before expiry. Apps never see the client secret or the minted token — the broker holds both and attaches the bearer at the edge.

Registering from the catalog

Client-credentials providers in the integration catalog prefill the token endpoint and the standard scopes, show you where to create the OAuth client and what scopes to grant it, and seed the integration’s first Knowledge entries. You supply the client id and secret. Anything the catalog doesn’t cover is a Build your own registration with the same fields, entered by hand.

How the credential reaches the app

Client-credentials integrations are proxied: the broker mints and refreshes the token and attaches Authorization: Bearer at the request edge. Injected delivery — handing a value to the app’s environment — isn’t offered for this kind, because a token that has to be refreshed can’t be a static injected value. Proxying is what makes the refresh transparent to the app.

// Call the upstream through the broker — the minted bearer is attached for you
const res = await fetch(
  `${process.env.GREENLIGHT_PROXY_URL}/market-data/v1/securities/AAPL/prices`,
);

The app never performs the OAuth exchange, holds the client secret, or sees the token. It calls the proxy URL; the broker keeps a valid token in front of the upstream.

Note

The upstream system’s logs show the OAuth client (the org-level service identity) as the actor on every call. Which end user’s Greenlight session caused a given call lives in Greenlight’s audit log.

Operating a client-credentials integration

The IT-admin workflow lives in Manage integrations. Briefly:

1. Register the integration — pick a catalog entry, or Custom for an uncatalogued provider — and enter the token endpoint and scopes.
2. Attach the credential: the OAuth client id and secret, stored write-only in your vault. The credential carries a stable slug, a free-text scope, and an approval policy, exactly as other kinds do.
3. Grant the integration to the apps that need it.
4. Rotate the client secret when your policy says to — the slug and every grant survive; the broker picks up the new secret on its next token mint, with no app redeploy.

Deleting a credential or a whole integration is guarded: Greenlight refuses while any app still holds an active grant and tells you which apps to revoke first.

Local development

A granted integration works locally too — an agent’s bundled greenlight CLI can use it while building. Because the integration is proxied, the laptop never holds the client secret or the minted token: greenlight run mints a short-lived, app- and user-scoped token and the app calls the same proxy URL the deployed app uses, while Greenlight performs the upstream OAuth exchange on the control plane. An agent can also read live results through the always-on inspectIntegrationApi tool, which returns results only — never the credential. See Develop locally.

Next

Manage integrations The IT-admin workflow, the catalog, and the decision criteria.

Service account integrations The static-key kind — a single IT-managed credential.

User-passthrough integrations When the upstream system needs to see the actual end user.

Data brokering How proxied delivery, token minting, and grants fit together.