Connection reference

What is a connection reference?

A connection reference is a Power Platform solution component that points to a connection for a given connector. A solution-aware flow or app binds to the reference instead of to the stored connection directly, which puts a layer of indirection between the logic and the credentials.

That layer is what makes a solution portable. In development the reference can point at a test account; when you import the solution into production, you attach the same reference to a production connection without editing a single action in the flow.

Connection references live in Microsoft Dataverse and belong to solutions. Flows built outside a solution usually use connections directly and have no need for one.

Connector, connection, and connection reference

These three sit in a stack, and the difference matters when something breaks.

A connector describes the triggers and actions a service offers. The SharePoint connector, for instance, knows how to reach lists, files, and sites through the underlying API, and a custom connector you build for an unlisted service behaves the same way.

A connection holds the stored sign-in context for that connector: a user identity, a service principal, or another supported authentication method such as OAuth.

A connection reference is the solution component that says which connection the solution's parts should use. It does not hold the password or token itself, only a pointer to the connection that does.

An environment variable solves a related but separate problem. It stores configuration that changes per environment, such as a site URL or a list ID. Many solutions need both connection references and environment variables.

A deployment example

A solution holds a cloud flow that reads documents from SharePoint and creates a record in Dataverse. The flow uses one connection reference for SharePoint and one for Dataverse.

In the development environment those references point at test connections. On import into test, the deployment picks connections with access to the test site and database; in production, production identities are attached. The flow definition stays the same, and only the references and configuration values differ, so nobody has to sign every action back in after each import.

After import, the owner or the deploying identity must be allowed to use each connection. A valid reference that points at an expired or inaccessible connection still fails.

How connection references support ALM

Solutions package flows, apps, and their dependent components. Connection references make the external links of those components explicit and swappable per target environment, which supports a fixed route from development to test to production.

A deployment settings file can record ahead of time which connection ID belongs to each reference, and a pipeline can apply those values during import. The Power Platform CLI generates a starter file with the pac solution create-settings command, leaving the connection IDs for you to fill in per environment.

Keep references purposeful. Two flows that use the same SharePoint site under the same managed identity can share a reference. Processes with different rights or owners should not quietly end up on the same connection.

Identity and security

Pick the running identity to match the business process. A personal connection can stop working when its owner leaves, changes a password, or loses access. A supported service principal is often the better choice for a central background flow.

Give a technical identity only the rights it needs. The connection reference does not narrow those rights; it only points at the connection, so check source permissions, connector policy, and flow sharing separately. Keep secrets in supported secret storage, never in the name or description of a reference.

Troubleshooting

An "invalid connection" error usually means the connection underneath has expired, been deleted, or become unavailable. Start by finding which reference the failed action uses and which connection is attached to it.

After an import, a reference may not have a valid connection yet, or the user turning the flow on may lack rights. Check too whether a newly added connector action created an extra reference that is not in the deployment settings. Give references unique, descriptive names; a list of references all called SharePoint followed by a random number makes both diagnosis and deployment harder than they need to be.