Manage integrations

Admin guide

Integrations are the upstream services your apps reach through the data broker. As an IT admin you control which services exist, the credentials they hold, and which apps may call them. This page walks the day-to-day workflow.

Each integration holds one or more named credentials. A credential is a stable slug (the handle an app binds a grant to — e.g. repo-readonly), a free-text scope describing what the key grants, and the secret itself. Apps request a specific credential by its slug. Each registry card also shows the base URL you entered at registration (or the database host for a connected database), so you can confirm the proxy target without reopening the wizard. The architecture under every integration — the proxy, workload identity, per-call audit — is Data brokering.

How an integration authenticates

Every integration is classified by one question: how does Greenlight obtain the upstream credential, and whose identity does the upstream see? That single axis — the auth mode — has three values:

Auth mode	What it means	Upstream sees
Service account	A static credential you paste once — API key, bearer token, or basic auth.	One shared identity for all app traffic. The default for most internal APIs.
Client credentials	OAuth 2.0 client-credentials; Greenlight mints and refreshes a machine token from the client id/secret you register.	A machine/application identity.
User-passthrough	OAuth token exchange — Greenlight swaps the signed-in user’s session for an upstream user-scoped token.	The actual end user, so upstream RBAC applies per person.

For a service account, you also tell Greenlight where the static credential goes on the wire — an Authorization: Bearer header, basic auth, a custom header (e.g. X-Api-Key), or a query parameter — because not every API uses the same placement.

Slack, GitHub, Google Workspace, Close, and Fireflies ship as catalog entries with service-account auth; Snowflake and Salesforce ship as catalog entries with user-passthrough auth. Anything the catalog doesn’t cover is a build-your-own registration.

Note

One catalog entry is served by Greenlight itself: the User Directory (greenlight-directory) lets granted apps read your org’s user roster — for people pickers, assignee dropdowns, and resolving stored user ids back to names. Registering it is a single confirmation with no credential to paste or rotate, but apps still need a granted credential, and every roster read is audited like any other proxied call. Each user exposes only an id, email, display name, and active flag. See Data brokering.

Note

A provider that supports both a shared-identity mode and a per-user mode is registered as two separate integrations — for example a salesforce service-account integration for background sync and a salesforce-user user-passthrough integration for interactive views. Each is single-mode, with its own credentials, grants, and proxy path. An app grants whichever one it needs.

Note

Workload identity is not an integration — it’s the per-pod cryptographic credential every app gets automatically. Apps authenticate to the data broker as themselves; the broker handles the upstream credential.

Register an integration

Registration always creates the integration and its first credential together — there is no credential-less integration to clean up later. You start from the integration catalog: a searchable, logo’d list of curated upstreams (GitHub, Slack, OpenAI, Salesforce, Snowflake, …). Picking a catalog entry prefills the display name, machine name, base URL, auth mode, and credential placement, and shows you exactly how to obtain that provider’s credential. The provider-defined auth mode and placement are visible but read-only; customer-specific names, URL placeholders, and fields such as a Basic username remain editable. For anything not in the catalog, Custom opens the same wizard with blank fields.

1. Open the Integrations page. Click + Register integration.
2. Pick a catalog entry — or Custom. A catalog entry (e.g. Slack, Azure SQL Database) prefills the fields below and surfaces step-by-step credential-acquisition instructions for that provider. Custom is for any HTTP API the catalog doesn’t ship.
3. Name it and point it at the upstream. Always: a display name and a machine name (lowercase, alphanumeric with dashes — e.g. hubspot-prod). Then, for an HTTP integration, the base URL and the auth mode (service account, client credentials, or user-passthrough). A catalog profile shows its provider-defined auth mode and credential placement read-only. For Custom service-account integrations, select one placement for the API key: bearer, basic, custom header, or query parameter, then fill any placement-specific field. For a connected database (the Azure SQL catalog entry), enter the connection target instead — host, port, and database name — plus the database auth mode: workload identity (recommended — Greenlight connects as its own managed identity, no secret to paste); SQL authentication (a username and password); or a service principal — an Entra app you register in the database’s own tenant, pasting its application (client) ID, its tenant ID, and a client secret. The service principal is the Entra route when the database lives in a different Microsoft Entra tenant than your Greenlight install (a managed identity can’t reach across tenants; SQL authentication also still works there), and works just as well for a same-tenant database when you’d rather grant a dedicated app than Greenlight’s own identity.
4. Choose how the credential reaches apps. Proxied (default for HTTP) — apps call GREENLIGHT_PROXY_URL and Greenlight swaps in the credential, which never reaches the app. Injected — Greenlight injects the bound credential into the app as an environment variable you name (e.g. HUBSPOT_API_KEY), and the app calls the upstream directly; the name can’t collide with a platform-managed variable. A catalog entry the proxy can’t broker offers only injected. An Azure SQL connected database is always proxied — apps send SQL plus separately bound parameters and receive one bounded JSON result grid; no connection string enters an app. Each authorized call requires a fingerprinted audit event that never stores SQL text or parameter values.
5. Add at least one credential. Give it a slug and a free-text scope. For most integrations you also paste the secret; a workload-identity database has none — the credential row is just the handle apps bind grants to, and access is whatever role you granted Greenlight’s identity inside the database.
6. Optionally, write the first Knowledge entry. Registration is often the moment you know most about why this integration is being added — which accounts or warehouses are in scope, which apps may touch it, house conventions. This field is for that: builder-facing context for your coding agents, never credential-acquisition instructions. Leave it blank and the integration simply starts with no Knowledge, same as before.
7. Save. Secrets land in Key Vault — write-only, never read back. The integration appears with its credential(s), and your Knowledge entry (if you wrote one) alongside it.

For an Azure SQL connected database, grant access inside the database first: the wizard shows the exact CREATE USER … FROM EXTERNAL PROVIDER / ALTER ROLE db_datareader ADD MEMBER … statements for this installation’s identity (including a SID-based variant when your server lacks a Directory Readers identity), and your DBA runs them with their own credentials — Greenlight never gets admin access. The role you grant is the boundary. db_datareader is recommended; use a separate identity and explicitly named scope for a write-capable role. Also allow Greenlight’s egress address through the database firewall — one source, not every app.

Where the provider allows it, register a dedicated account for the integration (a greenlight@yourcompany service login, say) rather than a person’s own credentials — the same posture Greenlight takes for source control. The integration’s actions then show up separately in the upstream’s own audit logs, and revoking it never locks a human out of their account.

Tip

Catalog and Custom integrations both start with no Knowledge entries. You, an app owner, or a builder agent during a real session can author the first connection notes and idiomatic queries on the integration’s card. See Curate knowledge.

Add a credential

Integrations are 1:N with credentials, so an upstream that exposes several keys (a read-only and a read/write GitHub App installation, say) is one integration with two credentials. To add another to an existing integration, open its card, click Add credential, and supply the slug, scope, and secret. Existing grants are unaffected; apps bind to the new slug when they request it.

Edit a credential

To correct a credential’s scope — the free-text description of what the key grants — click Edit on its row and save the new text. You don’t re-enter the secret (that’s Rotate), and the slug can’t be changed: it’s the handle apps bind their grants to, so renaming it would break every live grant. To effectively rename a credential, add a new one under the right slug and have the apps re-declare their grants. Edits are audited and show up immediately wherever the scope appears, including the credential list agents read before requesting a grant.

Per-credential policy

Each credential carries one setting you control on its row:

• Approval policy — manual (a grant an app declares for this credential lands in the Grants sub-view of the Integrations tab for you to review) or auto (the grant takes effect on merge, shown in the queue as auto-approved by policy). Default manual — grants wait for your review until you opt a credential into auto. Setting auto on a write-capable scope shows a non-blocking advisory.

Local development follows the grant. For a proxied credential the laptop never holds the secret: local runs call the real proxy with a short-lived, scoped token, and no value ever passes through the agent. For an injected credential, granting it is disclosing it: granted agents and developers can obtain the raw value, including on their own machines, and a value on a developer’s machine can’t be time-bounded or remotely revoked — rotation is the only way back. The dashboard says so at the two moments that decide it: when you choose injected delivery at registration, and when you approve a grant on an injected credential.

Tip

For an injected integration, prefer a dedicated, least-privilege account in the upstream system — one you can rotate or disable without breaking anything else. If a value must never reach developer hands, register the integration as proxied, or don’t onboard it.

Grant to apps and people

Registering an integration does not give anything access to it. Granting happens per credential, per principal — an app, or a person.

App grants arrive from merges: a grant the agent declared in greenlight.yml whose credential is set to manual approval shows up as a pending request once its PR merges.

Personal grants arrive from people: a user’s agent (or the greenlight CLI) calls requestCredentialAccess to ask for that user’s own access — for local scripts and analysis with no app. There is deliberately no request form in the dashboard — requests always come attributed from the requester’s own session; the dashboard is where you review them.

1. Open the review queue. The Grants sub-view of the Integrations tab lists pending requests from both apps and people, alongside the full granted inventory.
2. Approve or deny. Approve to grant; the decision is audited and effective immediately — the principal’s next call to the integration succeeds. A credential set to auto approval grants on request without landing in the queue (shown as auto-approved by policy).
3. Revoke any time. Revoking takes effect on the principal’s next call. A person re-requesting after a denial or revocation re-opens the request as pending — policy never overrides your decision.

Rotate credentials

Rotation is a single dashboard action on a credential — Replace secret on the credential’s row. You re-enter the secret; the slug, its scope, and every grant bound to it stay exactly as they were. Greenlight stores the new version in Key Vault, overwriting the old one in place.

How quickly running apps see the new value depends on how the credential reaches them. For a proxied credential, the broker resolves it on the next call — there’s no overlap window where both are valid, and no app restart. For an injected credential, the value is baked into each app’s environment at deploy time, so apps already running keep the old value until their next deploy; the Replace-secret dialog warns you and lists the apps affected.

If the upstream system’s rotation is automatic (rotating client-credentials tokens, for example), Greenlight follows the upstream’s lifecycle without manual intervention. Every rotation writes an audit event recording the integration, credential slug, and delivery mode — never the secret value.

Delete a credential

When a credential is no longer needed, click Delete on its row and confirm. Deleting deactivates the credential and destroys its secret in Key Vault.

Deletion is guarded: while any app or person holds an active grant (approved or awaiting review) on the credential, Greenlight refuses and the dialog lists the blocking principals with a link to the Grants sub-view filtered to that integration. Revoke each grant there first, then delete — Greenlight won’t pull a credential out from under a live holder. Grants that are already denied or revoked don’t block, and they’re preserved as history: deletion removes the credential from the listing but never erases the audit trail.

The slug stays reserved after deletion — register a replacement under a different slug, and apps re-declare their grants against the new slug.

Edit an integration

Click Edit integration on its card to correct the record without deleting and re-registering it. You can change the display name, the base URL (for an HTTP integration), the non-secret auth parameters, the delivery mode and its env var name, and — for a connected database — the host, port, and database name. The machine name, the auth mode, and (for a connected database) the engine stay read-only: each is a handle something else depends on — live app manifests reference the machine name, and the auth mode determines how every credential’s secret is shaped — so correcting one of those means registering a new integration rather than editing in place.

Switching delivery mode between proxied and injected (or renaming the env var an injected credential is injected under) never blocks, but running apps only pick up the change on their next deploy or restart — the same timing as a credential rotation above. If any app holds an active grant on the integration, the dialog lists it so you know who’s affected before you save.

Make an integration inactive

Use the Active / Inactive toggle on an integration card when you need to keep its configuration but stop agents and apps from using it — for example, while a production database is awaiting approval. Inactive integrations remain on the IT registry with their credentials, Key Vault secrets, and Knowledge intact. Agents cannot discover the integration, request a grant to it, read its integration Knowledge, or reach it through the proxy or local runtime until you turn it active again.

Deactivation is guarded like deletion: if any app or person has a pending or granted grant, Greenlight refuses and names the blocking access holders. Follow the link to the Grants sub-view, revoke each grant, then retry. Reactivating restores discovery and the preserved Knowledge, but it does not restore revoked grants — apps and people request access again through the normal approval flow.

Use Delete integration only when you intend to destroy its vaulted credentials and permanently reserve its slug. Availability is the reversible control.

Delete an integration

To remove a whole integration, click Delete integration on its card and confirm. The confirm step names every credential and Key Vault secret that will be destroyed. Deleting deactivates the integration and all its credentials and destroys their secrets in one step.

The same guard applies, one level up: while any app or person holds an active grant (approved or awaiting review) on the integration, Greenlight refuses and the dialog lists the blocking access holders with a link to the Grants sub-view. Revoke those grants first, then delete. Deletion removes the integration from the listing but never hard-deletes the rows, so the grant history is preserved. Two things to know afterward: an app whose manifest still declares a grant against the integration will fail its next merge — to that app it now looks like an integration that was never registered — and the integration’s name stays reserved, so you can’t re-register a new integration under the same name (register under a different name instead).

Revoke an app’s access

To pull one app’s access without deleting the credential, revoke its grant on the Grants sub-view of the Integrations tab (or from the app’s own Access tab). Find the grant, click Revoke, and confirm. The change is audited and immediate — the app’s next call to the integration returns a structured error, and the agent surfaces that failure to the user. Revoke is per-grant, so other apps holding their own grants on the same integration are untouched.

Review agent integration requests

Agents don’t request access through a tool call. When an agent decides an app needs an integration, it declares the grant in the app’s greenlight.yml — the integration plus the credential slug — and opens a PR. On merge, Greenlight diffs the declared grants against what the app already has: grants on auto-approval credentials take effect immediately, and anything on a manual credential lands in the Grants sub-view here, with the agent’s stated reason, the bound user, and the app context.

Approve or deny in the same interaction. When you approve, the app’s proxy calls start succeeding immediately — no redeploy.

Tip

Every integration grant, revoke, rotation, and deletion writes an audit event. The audit log is the source of truth for “when did app X get access to integration Y”, which is the question every compliance review eventually asks.

Next

Data brokering The proxy and audit layer behind every call.

Build your own integration The flow for registering a custom HTTP upstream.