The moment an agent connects to a real system, a CRM, a data warehouse, an internal API, you have a credential and an access decision to manage, and most designs manage them badly. The naive version stores the integration's API key, hands it to the agent, and lets it call whatever the key can reach.
That works in a demo and fails every audit, because it collapses five different things, what the integration is, which account, which operation, which secret, and who is allowed, into one. We keep them separate. A connector is a layered, controlled resource, and every layer is governed on its own.
A connector is not one thing
Pull a connector apart and there are several distinct pieces, each with its own controls. A definition is the integration itself: what kind of system this is, a warehouse, a CRM, an internal API, an MCP server, and which operations it can expose. An instance is a configured connection of that definition, usually tied to a specific authenticated account or a customer-managed credential.
A tool is a single operation the connector exposes: search, read, create, send, delete, administer. A credential is the secret behind an instance: an OAuth token, an API key, a service credential. And a grant is permission for a user, agent, or group to use or administer some of the above.
Defining a connector does not, by itself, give anyone access to it. Access comes only from a grant, and a grant can be as narrow as a single tool on a single instance. The definition is the surface of what is possible; the grant is the much smaller surface of what is allowed.
Administering a connector and using it are themselves separate grants. A workspace operator can be allowed to add an internal API connector without being granted use of every instance of it. And a definition can target either a conventional API or an MCP server proxied through a managed gateway, so the same layered model covers a hand-rolled integration and a standardized MCP tool surface alike.
Grants are per-tool, not per-connector
This is the part that matters most in practice. A grant does not have to mean the whole connector. It can expose exactly the operations a particular agent needs and withhold the rest.
A data-analysis agent can be granted search and read on one warehouse instance, with create, send, delete, and the administrative tools withheld entirely. The agent cannot call what it was not granted, even though the connector is perfectly capable of those operations for someone else. That is least privilege at the granularity of a single operation, which is the granularity that actually keeps an agent inside its lane.
Two ways a connector authenticates
Connectors authenticate in one of two ways, and the difference is about whose identity is behind the call. Some connectors run fixed workflow actions with a shared workspace credential: every permitted caller uses the same customer-approved auth context, which suits a connector that does one well-defined job for the whole workspace.
Others require a principal or admin to create an authenticated instance tied to a specific identity, the way a warehouse connector instance is tied to an authenticated warehouse role. The first answers calls as the workspace; the second answers as a named identity. Both still pass through the same grants, the same per-tool scoping, and the same gateway. What changes is the identity the target system sees.
The credential never touches the agent
Here is where it connects to the rest of the security model. The credential behind a connector instance is stored encrypted, with tenant-level isolation, and it is never handed to the agent sandbox or injected into the agent runtime. The sandbox is untrusted, so it gets no secret.
When the agent makes a connector call, the call runs through a hosted gateway that lives in the platform's trusted environment. The gateway holds the credential, applies the authorization checks, and only then invokes the target system. The agent expresses a tool call; the gateway, on the trusted side, supplies the credential. The two never meet inside the sandbox.
The target still enforces its own rules
Attaching a real identity at the gateway does not bypass the target system's own access control. When a query reaches a warehouse under an authenticated role, the warehouse still enforces what that role can see. Context narrows access in front of the system, through grants, per-tool scope, and severity. It does not widen it.
So a connector call passes two gates. The platform's authorization decides whether this agent may make this call at all. The target's own permissions decide what the authenticated identity is allowed once the call arrives. Two independent checks, neither replacing the other, and an agent has to satisfy both.
Credentials and grants have separate lives
A detail that turns out to matter a lot operationally: the credential and the authorization graph are decoupled. Rotating a credential, replacing an expired token or a leaked key, does not change who is allowed to use the connector. Revoking a grant, cutting off one agent's access, does not delete the credential other principals still use.
The thing you rotate for security hygiene and the thing you change for access control are different objects with different lifecycles, so you can do either without disturbing the other. Anyone who has rotated a shared secret and accidentally locked out half the company knows exactly why this separation is worth having.
When an agent needs a tool it does not hold
When an agent needs an operation above its grant, the escalation is the same intent mechanism used everywhere else. A read-only analytics agent that suddenly needs a higher-severity operation, or a tool it was not granted, does not get it by default and does not crash. It submits an intent to the invoking user, naming the tool, the scope, and the severity.
The platform checks the principal, the tool, the scope, denial overrides, and the approval before the request ever reaches the gateway, and the gateway is the only thing that ever touches the credential. Escalation at the connector layer flows through the same audited, bounded path as escalation anywhere else in the system. There is no special back door for integrations.
A worked example
Make it concrete with a warehouse connector. The definition exposes a handful of tools: run a query, describe a schema, list warehouses, and an administrative tool. A data-analysis agent gets a standing grant to run read-only queries against one instance, and nothing more.
When it needs a higher-severity operation, or a tool it does not hold, it files an intent to the invoking user. The platform authorizes the principal, the tool, the scope, the denial overrides, and the severity, and only then does the request reach the hosted gateway. The sandbox never sees the warehouse credential. And after all of that, the warehouse still enforces the permissions of the authenticated role the query arrives under. Several layers of narrowing on our side, and then the target's own on theirs. It is the same query a person would run, with more checks standing in front of it and the same one standing behind it.
The key never leaves the room
Connecting an agent to your systems is where access is real and where shortcuts are expensive. The shortcut, one key handed to the agent with full reach, is the exact thing every serious review is looking for. The alternative is not complicated, it is just separated: a connector is a definition, instances, tools, credentials, and grants, each governed on its own; the secret stays on the trusted side of a gateway; grants are per-tool; and the credential's lifecycle is decoupled from who is allowed. The agent gets exactly the operations it was granted, the target still enforces its own rules, and the key never leaves the room it is supposed to stay in.