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.

So you generally connect an account at the broadest scope that’s appropriate, and everything underneath 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.

Moving is safe: it’s the same connection, just relocated. You don’t have to re-authorize the account, and anything that was already relying on it continues to work — the connection keeps its identity across the move. Only where it’s available changes, following the inheritance rules above.

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 broad at the organization level and move the connection narrower later if you need tighter control.

Next steps

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