Connections

Connections link your personal accounts to the services available through the gateway. Each user authenticates independently, so an agent calling one of these services uses that user's own credentials and permissions rather than a shared account.

Connections (this article) link an end user's account to a service — each user signs in separately. They are distinct from the organization's OAuth client credentials, which determine which OAuth app the gateway uses to start that flow. See Credential modes for how organizations choose between using SecureAuth's app and bringing their own.

How connections work

1. An agent tries to use a tool that requires authentication (for example, sending a Slack message)
2. The gateway returns a link prompting the user to connect their account
3. The user clicks the link and completes the OAuth flow with the service provider
4. The gateway stores the credentials securely — encrypted at rest — and uses them for future requests

Once connected, all subsequent requests to that service use the user's credentials automatically — no re-authentication required. This exchange only happens for calls a policy already allows — a denied call never reaches the upstream service, so no connection is needed.

Per-user isolation

Connections are strictly per-user. An agent acting for one user cannot access another user's connections. This means:

• Each user only has access to the data their own account can see
• Actions are attributed to the correct user in the upstream service
• Revoking a connection only affects that user

Managing connections

Navigate to Connections in the dashboard to see the services that require a connection, each with its status and when it was last used.

• Connect — click to start the OAuth flow and link your account
• Disconnect — removes the connection and its stored credentials outright

Both actions need the manage_connections permission. Without it the page is read-only and neither button appears.

For admins: sharing and verifying

Connections are per-user, so each person links their own accounts. Two admin actions make that easier to hand off and to check:

• Copy portal link — in the Agent Instances header, copies the URL of the user portal so users know where to go to connect their agents. See Share the portal link.
• Connect — on a resource's detail page (Resources → your MCP) opens that resource's connect flow in the user portal and starts it right away, so you can confirm authentication works and tools populate before handing the resource to users. It appears only for resources that need a per-user OAuth connection.

Connection statuses

Most of the time the page shows each service as Connected or Not connected. Two things keep it that simple:

• Tokens refresh on their own. The gateway renews expiring access tokens in the background and retries once if a provider rejects a token mid-call, so a working connection keeps working without you signing in again.
• Disconnecting removes the connection. It leaves no lapsed record behind. The credentials are deleted and the service goes back to Not connected.

Two more statuses need your attention: Revoked and Expired.

Revoked. Sometimes the service itself cancels the app's access. You might revoke it in the provider's own settings. An admin at the service provider might remove it. The refresh token might stop being accepted. In each case the gateway marks the connection Revoked. It also records a connection-revoked audit event.

Expired. An admin can limit how long a connection stays valid (see Connection lifetime). The gateway marks the connection Expired once it passes that limit. It records a connection-expired audit event.

In both cases, the next tool call that needs that service returns the connect link again. Click Reconnect to sign in again.

Connection lifetime

By default a connection stays valid until the user disconnects it or the provider revokes it. On Resources → your MCP → Settings you can set two limits:

• Maximum age expires the connection this long after the user connected it, no matter how often they use it.
• Idle timeout expires the connection this long after the user's last call to that resource.

Both limits are optional and work independently. Leave a field empty to set no limit of that kind. Set either one in seconds, minutes, hours, or days. Editing them needs the manage_mcps permission.

Expiry deletes the stored credential, so the user must sign in again before an agent can use that resource on their behalf. Expiry is not immediate: a connection can stay usable for a few minutes after it passes a limit.

Reconnecting starts a new maximum-age window.

Next steps

• Credential modes — how your organization chooses the OAuth app behind these connections.
• Policies — decide which calls are allowed to use a connection at all.
• Audit log — see connection-created, expired, and revoked events.