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.

The Integrations page showing a request to connect awaiting review and registered integrations as cards with an availability switch, each credential with its grant count, its review setting and who it is granted to.

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. The registry card itself stays compact — the base URL you entered at registration (or the database host for a connected database) is confirmed through Edit integration. 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	Per-user OAuth: each person connects their own account at the upstream’s sign-in once, and Greenlight stores and refreshes a token for them.	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, Google Workspace, Close, HubSpot, Asana, Fireflies, and Axiom ship as catalog entries with service-account auth; GitHub defaults to an org-owned GitHub App (client-credentials auth, with a personal access token as a non-default escape hatch); Microsoft Graph defaults to user passthrough — per-user OAuth, prefilled from your tenant id (Microsoft Graph) — and offers an Application permissions (app-only) client-credentials profile beside it, registered as a second integration (microsoft-graph-app) for system mail sent from named mailboxes with no user signed in: its setup guide confines the registration to those mailboxes with Exchange Online RBAC for Applications, and you must not also consent Mail.Send as an application permission in Entra, because that consent adds tenant-wide reach on top of the scope; Box registers with client credentials but acts as each signed-in person, without a connect step, from your Box app’s Client ID, Client Secret, and Enterprise ID, and is always proxied (Box); Microsoft Fabric is one tile whose form takes one Entra app registration and registers whichever of the REST API and API for GraphQL, Power BI semantic models, and SQL endpoints (one integration per host and database, named fabric-sql-<database>) you tick, as User passthrough (each signed-in person) or as a Service identity (one service principal, for scheduled jobs); semantic models are user passthrough only (Microsoft Fabric); Snowflake registers as user passthrough through Snowflake OAuth, with one Snowflake role per credential, named when the credential is added and fixed once saved (Snowflake); Salesforce and NetSuite also list a user passthrough profile, which isn’t selectable yet: the Register dialog shows it disabled and registration refuses it, whether it comes from the dashboard or the API. Salesforce and NetSuite register with client credentials in the meantime. Any OAuth upstream can be registered as user passthrough through Custom, where you supply its authorize and token URLs and scopes (User passthrough integrations). Anything else the catalog doesn’t cover is a build-your-own registration.

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. For anything not in the catalog, Custom opens the same wizard with blank fields.

The wizard asks one thing at a time. Once you pick an integration, a stepper across the top — Set up · Name · Connect · Credential · Delivery · Review — marks the step you’re on; Continue checks only that step, and you can click any step’s number to jump to it, ahead or behind — Register still checks every step. The integration’s setup guide stays above the fields on later steps, collapsed. A step with nothing to ask is left out, such as Delivery for an integration that can only be proxied.

Open the Integrations page. Click + Register integration.
Choose a catalog entry — or Custom. A catalog entry (e.g. Slack, Azure SQL Database) prefills what follows. Microsoft Fabric uses four of these steps — Set up, Connect, Credential, Review — where you choose User passthrough or Service identity, tick what apps need, and enter the Entra app registration once (Microsoft Fabric). Custom is for any HTTP API the catalog doesn’t ship.
Set up. For a catalog entry, read the step-by-step instructions for getting that provider’s credential ready, and pick a connection profile if the entry offers more than one. For Custom, choose how the service authenticates: service account (a static key), OAuth 2 client credentials, or user passthrough (each person signs in, and calls run as them).
Name it. Enter a display name. The machine name — the lowercase, hyphenated name apps and builder agents refer to — fills in from it as you type (HubSpot — Prod becomes hubspot-prod); a catalog entry keeps its own suggestion while you leave its display name alone. Click Edit to type your own. The machine name can’t be changed after registration.
Connect it to the upstream. For an HTTP integration: per-customer URL values the catalog leaves as {placeholder} holes — a NetSuite account ID, a Teams tenant, a Jira site, a Salesforce My Domain — appear as named fields with a live preview of the resolved URL, along with provider-specific values such as a Basic username or multi-header realm. The catalog’s auth mode, credential placement, and any literal base URL sit in a closed Provider defaults section you can expand to inspect. For Custom service-account integrations, enter the base URL and select one placement for the API key: bearer, basic, custom header, or query parameter. For a Custom user passthrough integration, enter the upstream’s authorize URL, token URL, the scopes each person authorizes when they connect, and optionally its revocation URL, which must be on the same server as the token URL; on Microsoft Entra the URLs name your tenant id, never /common, and the scopes include openid, profile, and offline_access (elsewhere openid and email), so Greenlight can prove the connected account belongs to the person who connected it and request a refresh token. A catalog profile such as Microsoft Graph fills the URLs and scopes itself from the tenant id you enter; Microsoft Fabric needs the tenant id as a GUID, never the domain name. A user passthrough integration is always proxied. For a connected database (Azure SQL Database, or a Fabric SQL endpoint reached from the Fabric form’s link for injected delivery), enter the connection target instead — host, port, and database name. Its auth mode is the connection profile you picked in Set up. Azure SQL offers three: 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. 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. A Fabric Warehouse offers only the service principal: Microsoft Fabric does not support SQL authentication at all. Its host is the SQL connection string from the item’s settings in the Fabric portal (<guid>.datawarehouse.fabric.microsoft.com), and the database name is the warehouse item name — leaving it blank lands the connection on master.

Greenlight checks it can reach the upstream before you continue. From inside your Greenlight cluster, the check covers every address the integration will use: the base URL, the OAuth token URL when the auth mode has one, or a database’s host and port. For a URL the name must resolve, a connection must open, TLS must complete with a certificate Greenlight trusts (for an https URL; an http URL has no TLS stage), and the upstream must answer; any answer counts, because no credential is sent. For a database the name must resolve and the port must accept a connection. Click Check reachability to run it yourself; Continue runs it if you haven’t, and Register runs it again if you change an address afterwards. An unreachable address keeps you on this step and names the host, the port, and where the connection failed. On a private install whose outbound traffic goes through your firewall, the message says so: the upstream isn’t necessarily down, and your network team needs to allow that host and port from the Greenlight network. Greenlight never connects to loopback, link-local, or cloud metadata addresses; addresses on your private networks are fine.
Add the first credential. Registration collects exactly one. Paste the provider’s key, secret, or password — the field is named for what you paste (API key, bot token, client secret, private key, password), and the empty-field example is specific to that integration (an OpenAI key looks like sk-…, a Slack bot token like xoxb-…). Some credentials also carry an upstream id: a client ID, a database username, a service principal’s application and tenant IDs, or a Snowflake role. For NetSuite-style certificate M2M, click Generate certificate, download the public certificate to upload in the provider, and copy the Certificate ID back. Auto-approve grants starts on; turn it off if requests should enter IT review instead. The credential’s identifier — what builder agents name when they request it — defaults to the machine name followed by -credential (azure-credential), and its description to the display name followed by “Access” (“Azure Access”); change either under Advanced, which starts open. Builder agents read the description to choose a credential, so say what it reaches — the Sales workspace and the Revenue semantic model, say. A workload-identity database has no secret — the credential is just the handle apps bind grants to, and access is whatever role you granted Greenlight’s identity inside the database. Add further credentials later from the integration’s card.
Choose how the credential reaches apps. Proxied (recommended and the 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, and this step just asks for the variable name. A connected database is proxied by default — 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. A database registered with a service principal can instead be injected, for an app that needs its own driver: you choose an env var prefix (e.g. CAST_DB), and apps receive CAST_DB_HOST, CAST_DB_PORT, CAST_DB_DATABASE, CAST_DB_TENANT_ID, CAST_DB_CLIENT_ID, and CAST_DB_CLIENT_SECRET. Injected queries are not audited by Greenlight, and the app pods need network access to the database.
Review. The summary lists the name, address, authentication, credential, and delivery, each with an Edit link back to its step.
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 — what data the integration reaches (which workspace, which semantic model), schema, gotchas — never credential-acquisition instructions. Leave it blank and the integration simply starts with no Knowledge, same as before.
Read what a grant means, and accept the data-access terms once. Every registration shows a short panel: granting this credential to an app or a person lets their coding agent call the upstream with everything the key can do, Greenlight brokers and audits proxied calls but does not narrow the key, and the key should be least-privilege on a dedicated upstream account. Until your organization has accepted the data-access terms, the panel ends in a checkbox and Register stays disabled until you tick it. Acceptance is recorded once, with your name and the terms version, and audited. Later registrations still show the panel, without the checkbox.
Register. Secrets land in your cloud’s managed secret store—write-only, never read back. The integration appears with its credential, 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. The role also bounds exploration: a builder’s agent holding a grant, the app’s or their own, can run SQL against the database through inspectIntegrationDb, which rolls its statements back but cannot guarantee a write never lands. Also allow Greenlight’s egress address through the database firewall — one source, not every app.

A Fabric SQL endpoint registered as a service identity is granted differently, and the Fabric form’s service-principal guide walks the whole sequence. Three steps fail silently if you skip them. A Fabric admin must enable Service principals can use Fabric APIs in the tenant settings — that setting is normally scoped to specific security groups, so your service principal has to be a member of one. The service principal then needs workspace access (Viewer is least privilege) or per-item permissions plus GRANT SELECT. Finally, Fabric only establishes the service principal’s security token on a successful Fabric REST API call — connecting to the SQL endpoint never does it — so make one such call before relying on the registration, and again at least every 30 days. Registering the Microsoft Fabric catalog entry alongside the warehouse is the straightforward way to keep that current. None of this applies to the warehouse’s Per-user OAuth profile, where each query runs as the signed-in person; see Fabric SQL endpoints. On a private install whose outbound traffic leaves through your firewall, that firewall must allow each SQL endpoint on TCP 1433 as MSSQL/TDS traffic: a protocol-aware firewall that inspects port 1433 as HTTPS breaks the connection even with the port open. Separately, a workspace with IP firewall rules must list Greenlight’s outbound IP address.

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.

Upstreams that serve only plain HTTP

Base URLs are https:// by default. A service-account (static key) integration may use an http:// base URL for an upstream that offers no HTTPS, such as an on-premises service:

The Connect step warns you first. Over plain HTTP, anyone on the network path can read or change requests and responses, and can read the API key Greenlight sends. Continue and Register stay blocked until you tick the box that says you understand. Use it only when the upstream has no HTTPS, preferably on a private network.
Greenlight suggests HTTPS when it can. If the reachability check finds that the http:// address redirects to https:// on the same host, the step shows that URL and a Use the HTTPS URL button.
The card says so. The integration’s card, and its Edit integration form, show a Not encrypted badge. The registration audit event records that the base URL is plain HTTP.

OAuth client-credentials and user passthrough integrations always need an https:// base URL, because they send an OAuth token on every call. When you register through the REST API instead of the dashboard, send allowInsecureHttp: true with an http:// baseUrl; without it the request is refused.

Upstreams whose certificate does not verify

Greenlight checks every https:// upstream’s certificate against the system’s trusted roots. Two kinds of server fail that check even when a browser opens them without complaint: one that sends its certificate without the intermediate that links it to a trusted root (browsers fetch the missing piece; Greenlight does not), and one signed by your own internal CA. The reachability check then stops at the TLS stage and says the upstream’s certificate chain did not verify.

A service-account (static key) integration has a Certificate section on the Connect step, closed until you need it. When the chain does not verify, the step says so and offers to open it. Pick one of three:

Verify (the default). The system roots, nothing else.
Trust an extra certificate. Paste the PEM, or upload a .pem, .crt, or .cer file. Greenlight lists each certificate with its subject, issuer, expiry, and SHA-256 fingerprint so you can confirm it is the one you meant. The certificates are added to the system roots, never used in place of them, and the hostname is still checked. For an incomplete chain, paste the missing intermediate, which the issuing CA publishes at the URL in the server certificate’s Authority Information Access field. If that intermediate is signed by a root newer than the ones Greenlight ships with, paste the next certificate up as well, and so on until the chain reaches a root Greenlight trusts; the check tells you when it does.
Skip verification. Greenlight accepts any certificate. Anyone between Greenlight and the upstream could then pretend to be it and read the API key Greenlight sends, so the option sits behind a warning and a checkbox you must tick. Prefer trusting the right certificate.

The setting is per integration, and applies to every call Greenlight makes to that integration’s base URL: the proxy, the reachability check, and Test. The card shows Extra certificate trusted or a Certificate not verified badge. The registration and edit audit events record the mode and the certificates’ fingerprints, never the PEM.

More detail

Up to 16 certificates and 64 KiB of PEM. A paste that contains a private key, or a block that is not a certificate, is refused without saving anything.
The setting is for HTTPS service-account integrations only. An OAuth token URL always uses the system roots.
On an injected integration the app calls the upstream itself, so the setting covers only Greenlight’s own reachability check and Test.
Through the REST API, send tlsConfig: { "mode": "custom_ca", "ca_pem": "<PEM>" } or { "mode": "skip_verify" } on register or edit, and tlsConfig: null to return to Verify.

Per-user OAuth (user passthrough)

A user passthrough credential is one upstream OAuth client: on Microsoft Entra an app registration, elsewhere the OAuth client the upstream issued. Enter its client (application) ID beside the slug and paste its client secret as the credential. Every app granted that credential reaches exactly that client’s permissions, as each signed-in person.

Each person connects their own account once, from the Connect button an app shows where a feature needs it; Greenlight signs them in to the upstream through that client. Greenlight asks silently first, so a person whose browser already has an upstream session and whose administrator has granted the client admin consent sees nothing; only when the upstream insists (consent, a second factor, a sign-in) does one screen appear. Before storing anything, Greenlight confirms the connected account is that person’s: on Entra the tenant and object id recorded at their Greenlight sign-in, on Snowflake the username, elsewhere a verified email. A mismatch stores nothing and tells the person which account was refused.

People disconnect their own connections, and IT revokes one or all of a person’s through the API; deactivating a person deletes theirs, and deleting the credential or its integration revokes every connection made through it. Each revocation is audited with who and why, and Greenlight tells the upstream where it offers a revocation endpoint. A connection the upstream stops honouring is marked for reconnection, and the app shows the person a Reconnect button the next time they use a feature that needs it.

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.

Test a saved credential

Each credential on an integration’s card has a Test action. It makes one read-only call with the stored secret, the way the proxy will, and shows the answer under the credential. The credential then carries a badge with the outcome, when it was tested, and who tested it, so a key that has expired or been rotated upstream shows up before an app fails. When an OAuth token endpoint refuses the credential, the result quotes the provider’s own explanation, such as Salesforce’s “request not supported on this domain”.

A per-user OAuth credential has no shared secret to call with, so its action is Test sign-in instead. It opens the connect in a new tab and you sign in as yourself, exactly as a person using an app would; registering a per-user OAuth integration ends on the same step. A pass shows the account Greenlight matched and leaves you connected. A failure shows the cause and the fix, and if the tab never comes back (the provider showed its own error page) the card lists the provider’s common setup errors after a minute. See User passthrough. Box and Google Workspace delegation have no sign-in to test.

Edit a credential

Click Edit on a credential row to manage it in the same field order used when adding one. The slug remains visible but disabled because it is the handle apps bind their grants to. You can update the free-text scope and approval policy, or enter an optional replacement secret; leave the secret blank to keep its current value. For an OAuth client-credentials integration the secret is entered as its parts — the client ID plus client secret, or for certificate-based (private_key_jwt) providers the client ID, Certificate ID, and private key (generate a fresh certificate or paste), or for a GitHub App the App ID, Installation ID, and private key — always together, since the stored value is the composed set. Changing a GitHub App installation id here does not re-point the mint; the stored token URL already names the installation. To effectively rename a credential, add a new one under the right slug and have the apps re-declare their grants.

Per-credential policy

Each credential carries two settings you control from its Edit dialog (and when adding it):

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). Credentials created during integration registration default to auto; credentials added later to an existing integration default to manual. You can change either before saving.
Required groups — mark a sensitive credential as usable only by members of chosen groups: any Greenlight group, or any directory group you have registered on the Users page. A person can use it only while they are in one of the groups; leaving a Greenlight group takes effect on their very next call, and leaving a directory group takes effect at their next sign-in, when Greenlight learns their directory groups. Only a requester who is already in a group is auto-approved. An app keeps its grant only while everyone who can open it is inside the requirement: the app is restricted, every group on its Access tab is a required group, and its owner, co-owners, and people added by name are all members. Platform admins don’t count against it. Binding the required group itself on the app’s Access tab is the durable way to satisfy it, since membership changes in that group can’t break it. Nothing here changes who can open an app, and a merge never fails because of it. A group a credential requires can’t be deleted or deregistered until you remove it from the credential.

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 moments that decide it: when you choose injected delivery at registration, when you approve a grant, and when you revoke one. The revoke confirmation also surfaces pull history so the reviewer can assess whether upstream rotation is needed.

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.

Each integration card has one Grants section instead of a separate credential table. Its header shows how many grants bind to that integration, and a small Review needed badge appears when someone is waiting for approval. Each credential sits on its own compact line with its title, description, auto-approval policy, and Edit/Delete actions; the users and apps that requested or hold access are behind a small Access granted to dropdown under each line. Pending rows can be approved or denied there; granted rows can be revoked, using the same confirmation and optional audit reason as the Grants sub-view.

Approving a grant on a proxied credential says what you are agreeing to before you confirm: which app or person’s agent can call which system, with which credential and its recorded scope, that every call is audited, and that you can revoke the grant there.

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.

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. You don’t have to watch it: Permission requests under Settings → Notifications is on from the start, so Greenlight emails every administrator when a merge creates new pending requests, and posts to your Slack channel if you have registered one — one message per merge, listing each integration, credential, and who asked. A merge with too many to fit one Slack message lists the first of them and a count of the rest, and the link opens the queue with all of them. Email still needs a sender, and if your install has none that section tells you so; switch the category off there if you would rather watch the queue yourself.
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). For an app grant, deciding it emails the app’s owner and editors with the outcome — no setting to turn on, since it’s a direct reply to their own request rather than an admin alert.
Held grants. When an app’s access is wider than a credential’s required groups, its grant sits in the queue as Held, with the reason: which credential, which groups, and what is wider (the app is open to the whole org, a group on it isn’t required, or someone on it isn’t a member). Approve stays disabled because approving it wouldn’t last. The owner sees the same reason on their app’s Access tab. Held grants aren’t in the new-requests email, because they wait on the owner rather than you; you’re emailed when one lands in your queue. Once they narrow the app, the grant returns by itself: to granted if you had approved it or the credential auto-approves, otherwise back into your queue. Widening the app again holds it again, and each hold and release is audited.
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.

An app that calls an integration it holds no approved grant for is refused by the data proxy every time. When the app never requested a grant for that integration at all, the first refusal also sends your administrators an app health alert naming the app and the integration, so code reaching beyond what was declared is noticed rather than only logged. A grant waiting in your review queue, or one you denied or revoked, is refused just the same but raises no alert: it is already your decision. You get one alert per app and integration, and the next waits until a day has passed with no refused call.

Rotate credentials

Rotation lives in two equivalent places: Edit on the credential’s row, and Edit integration, which lists a write-only replacement per credential. Both mirror Add credential: the immutable slug stays visible, the secret fields are optional, and entering a new value replaces the stored one while blank keeps it. Client-credentials secrets are re-entered as their parts (id + secret, or id + certificate + private key, or App ID + installation ID + private key) together. You can generate a fresh certificate for private_key_jwt providers. Changing a GitHub App installation id on rotate does not re-point the mint — the stored token URL names the installation. The slug and every grant bound to it stay exactly as they were.

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 edit 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 cloud-managed secret. On a user passthrough integration it also revokes every person’s connection made through that credential.

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 — for a Google Workspace integration that includes the OAuth scopes, so scopes entered wrong at registration are fixed here rather than by starting over — 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.

For an OAuth integration, the token URL is editable too:

From the catalog, with a value you typed in (a Salesforce My Domain, a DealCloud site, a Microsoft tenant id): edit that value, and Greenlight rewrites the base URL and the OAuth token URL together, so they always point at the same org.
Custom, or no longer matching the catalog: the OAuth token URL is a field you can correct directly.

Changing the base URL, the OAuth token URL, or a database’s host or port runs the same reachability check as registration before the change saves, and an unreachable address is refused the same way. Changing a service-account integration’s base URL to http:// shows the same plain-HTTP warning and checkbox before Save. The edit form also carries the Certificate section; changing it re-runs the reachability check under the new setting before it saves.

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, managed 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 confirmation names every credential and cloud-managed 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.

Review requests to connect a new system

The requests above are about integrations you have already connected. A separate queue, Requests to connect, sits at the top of the Integrations sub-view and answers a different question: someone’s agent needs data from a system your org hasn’t connected at all.

Those requests come from a builder agent or the CLI — there’s no form a citizen developer fills in. Each row shows the system, who asked, when, and why in their own words.

Approve & register records your decision and opens the usual Register dialog, already filled in with that system. Approving on its own connects nothing — the integration exists once you finish registering it, exactly as if you’d started from the catalog yourself.
Decline asks you for a reason and records it. Say what would change the answer: the person can raise the request again later, and a decline they can’t understand just becomes a repeat request.

Because approving isn’t connecting, it’s easy to approve on a busy afternoon and never come back to the Register dialog — and the person who asked has no way to tell the difference. If a request has been approved for a week and the system still isn’t registered, Greenlight emails you about it, and posts to Slack if you have registered a channel, then weekly until it’s connected. Finishing the registration is what stops it — a repeat ask from the person waiting doesn’t, and an approved request can no longer be declined.

Connection requests are never auto-approved, whatever a credential’s approval mode says. Connecting a new external system is a bigger decision than widening access to one you already trust, so a person makes it every time.

The queue is only there when something is waiting — an empty state would be permanent furniture on a page you visit for other reasons.

The pending connection queue and the Grants tab’s pending count refresh automatically every 15 seconds while you are viewing the dashboard. New requests appear without a page reload, and a decision another administrator makes updates the queue. An open registration or decision form keeps the values you have entered.

If a temporary refresh fails, the connection queue stays visible with a retry notice, and the Grants badge keeps its last count. Denied access clears cached requests and counts; they return only after a successful read restores access.

These reach you by email too, and in Slack when a channel is registered: Requests to connect a new system under Settings → Notifications is on from the start, and it covers the weekly reminder above as well as the original request. It’s separate from the pending-permission-request category, so you can keep one and switch the other off.

Both of those mail you when a request arrives. The weekly digest catches what nobody answered: alongside Knowledge awaiting a decision, its Monday roll-up counts the grants and connection requests still sitting in the queue — and the requests you approved where the system was never actually connected, which leaves the person who asked no better off than a denial would have.

Data brokeringThe proxy and audit layer behind every call.

Build your own integrationThe flow for registering a custom HTTP upstream.