Connection scopes

Every connection lives at a scope. The scope decides who can use the connection — which agents get to act on that account. Choosing the right scope lets you connect an account once and share it exactly as widely as you intend.

The four scopes

Alfe organizes work into a hierarchy, and a connection can sit at any level of it:

• Organization — available across your entire organization. Best for shared accounts that many teams and agents use, like a company GitHub organization or a shared accounting account.
• Team — available to a specific team and everything within it. Best for tools one team owns.
• Project — available to a single project. Best for an account tied to one piece of work.
• Agent — available to a single agent only. Best for an account that belongs to just one agent and shouldn’t be shared.

Inheritance: connections flow downward

Scopes nest, and connections are inherited down the hierarchy. A connection at a broader scope is automatically available to everything beneath it:

• An organization connection is available to every team, project, and agent.
• A team connection is available to that team’s projects and agents.
• A project connection is available to that project’s agents.

Connect an account at the narrowest scope that includes the intended agents. Everything underneath that scope can use it without connecting again.

When you look at a team, project, or agent in the Connections hub, you’ll see both its own connections and the ones it inherits from a parent scope. Inherited connections are shown for context but are read-only from the child view — to change one, you manage it at the scope that owns it. The hub links you straight to that source scope.

Most-specific wins

When the same provider is connected at more than one level, the most specific connection applies. If an agent has its own connection for a provider, that one is used; otherwise Alfe falls back to the project’s, then the team’s, then the organization’s.

That means you can set a sensible shared default at the organization level and still override it for a particular team, project, or agent by connecting a more specific account there.

Moving a connection between scopes

You can move an existing connection to a different scope from the Connections hub — for example, to narrow an organization-wide account down to a single team, or to promote a project connection up to the whole organization.

To move a connection:

1. Open the Connections hub in the dashboard at app.alfe.ai.
2. Find the connection and choose Move.
3. Pick the new scope.

A move preserves the connection’s identity and stored authorization. Its availability changes: agents outside the new scope can lose access, and agents inside it can gain access. Check which agents rely on the connection before moving it; preserving its ID does not preserve their authorization.

Choosing a scope

A quick rule of thumb:

• Shared by everyone → organization.
• Owned by one team or one project → team or project.
• Belongs to a single agent → agent.

When in doubt, start with agent scope and widen it only after confirming which other agents should be able to use the connected account.

Next steps

• See what you can connect and how to manage it: Providers & managing connections.
• Walk through the connect flow: Connecting an account.