Connection references are the mechanism that lets your Power Automate flows travel cleanly between dev, test, and production without hardcoded credentials. This lesson teaches you how to create, map, share, and update them so environment promotions never break a running flow.
You've built a Power Automate flow that connects to SharePoint, sends emails via Outlook, and writes records to Dataverse. It works perfectly in your development environment. Then you export the solution and import it into production — and suddenly the flow is broken. The connections are missing, or worse, they're still pointing to the wrong accounts. Your production flow is authenticating as your personal Microsoft 365 account instead of the shared service account it's supposed to use. This is one of the most common — and most disruptive — problems teams run into when promoting flows across environments.
The fix isn't patching connections after deployment. The fix is understanding connection references: a Power Platform mechanism that decouples the identity of a connector inside your flow's logic from the actual credentials used to authenticate at runtime. Done right, connection references let your flow definition travel cleanly from dev to test to production while the credentials get swapped out at each stop without touching the flow itself.
By the end of this lesson, you will understand exactly how connection references work, how to create and map them correctly, how to share them so the right people can maintain them, and how to update credentials across environments without triggering broken flows or re-deployment headaches.
What you'll learn:
This lesson assumes you understand what Power Automate solutions are and why you should build flows inside them rather than outside. If you're not yet comfortable with solution-aware flows and environment promotion, start with Deploying and Managing Power Automate Solutions Across Environments: ALM Pipelines, Solution-Aware Flows, and Environment Variables for Enterprise-Scale Delivery first. You should also know how to navigate the Power Platform maker portal and have access to at least one non-default environment.
Before connection references existed, connector credentials were baked directly into flows. When you exported a solution and imported it elsewhere, those embedded connections either broke immediately (because the target environment didn't recognize them) or — more dangerously — they continued authenticating as the original account. Imagine a flow that archives SharePoint files quietly running in production using a developer's personal credentials. That developer leaves the company, their account gets disabled, and suddenly every archive operation in production fails at 2am.
Connection references solve this by introducing a layer of indirection. Think of it like a DNS record: your application doesn't connect directly to an IP address — it connects to a hostname, and DNS resolves that hostname to the right IP in each environment. A connection reference is the hostname. The actual authenticated connection (the credentials) is the IP. You can point the reference at different credentials in different environments without changing the flow logic at all.
More precisely: a connection reference is a solution component that acts as a named placeholder for a connector type. Your flow binds to the reference. The reference binds to a connection. In production, you swap which connection the reference points to. The flow never needs to know the difference.
Key insight
Connection references are solution components, which means they travel with your solution package when you export and import. The connection they point to is environment-specific and stays behind — only the reference crosses environment boundaries.
A connection reference has three key properties you need to care about:
Inside a flow's action or trigger configuration, you don't select a raw connection. You select a connection reference. The maker portal shows this transparently — it looks like you're just picking a connector, but under the hood a reference is being created or assigned.
Note
One connection reference can serve multiple flows within the same solution. This is intentional. If three flows all need to read SharePoint, you create one SharePoint connection reference and all three flows use it. When you need to rotate the SharePoint service account credentials, you update the reference once and all three flows immediately get the new credentials.
You should never build flows outside a solution and then try to move them in. That path leads to connection headaches. Start by creating your solution first, then build flows inside it.
Navigate to make.powerapps.com, switch to your development environment using the environment picker in the top-right corner, and select Solutions from the left navigation. Either open an existing solution or click New solution and fill in the display name, publisher, and version.
Inside your solution, click New → More → Connection Reference. The dialog will prompt you for:
Contoso SharePoint – Service Account or Contoso Outlook – NotificationsAfter saving, the connection reference appears as a component in your solution's component list, just like a flow or an environment variable would.
When you create a new flow inside the solution (New → Automation → Cloud flow), the flow designer will prompt you to select a connection for each action that needs one. If you've already created a connection reference in the solution, it will appear in the dropdown alongside raw connections. Select it. The flow is now bound to the reference rather than directly to credentials.
Tip
If you're editing an existing flow and want to verify it's using connection references rather than direct connections, open the flow in the designer and check any connector action. Look at the connection selector — if it shows a reference name rather than an account name, you're in good shape. If it shows something like "user@contoso.com," the flow is using a direct connection and you should migrate it.
When you export your solution as a managed package (the right choice for production deployments), the connection reference component is included in the package. The ZIP file contains an XML definition of the reference — its name, its connector type, and a pointer to the connection it was using in the source environment.
That pointer to the source connection is intentionally broken when the solution arrives in a new environment. The target environment has no knowledge of the source environment's connections. This is correct behavior — it forces you to explicitly map the reference to an appropriate connection in the target environment during import.
When you import a managed solution that contains connection references, the Power Platform import wizard presents a connection mapping step. For each connection reference in your solution, it shows:
This is where environment-specific credentials get wired in. For your production SharePoint connection reference, you'd select (or create) a connection authenticated as your production service account rather than your developer account.
If you skip this step or accept the default (which may be empty or incorrect), the flow will import but fail at runtime because the reference isn't mapped to a valid connection.
Warning
A flow imported without valid connection reference mappings will appear to import successfully but will show as "Connection invalid" when you try to run it or turn it on. Always verify that all references are mapped to active connections immediately after import before marking a deployment as complete.
Let's make this concrete. Imagine you're deploying a solution called Contoso Invoice Processor that includes:
Your solution contains three connection references:
Contoso SharePoint – Invoice ProcessingContoso Outlook – NotificationsContoso Dataverse – Invoice RecordsIn development, these point to your developer credentials. In production, they should point to:
invoiceprocessor@contoso.com) with read access to the invoices libraryinvoicenotifications@contoso.com)When you import into production, you create or select connections for each of those production accounts in the mapping dialog. The flow definition doesn't change at all — only the mapping changes.
This is also why it's worth investing time in your environment strategy early. Without clearly separated environments and dedicated service accounts for each, connection reference mapping becomes muddled and error-prone.
For Dataverse connections specifically, many teams use service principals rather than named accounts. If you're not familiar with that pattern, Service Principals and Application Users for Unattended Power Automate Deployments covers the setup in detail.
A connection reference is only as reliable as its underlying connection — and that connection belongs to someone's account. This creates a subtle but important governance problem: if the connection under a reference is owned by Alice, and Alice's account is disabled or her password changes, every flow using that reference breaks.
There are two dimensions of sharing to understand:
Other makers who need to edit flows that use a connection reference should be co-owners of the solution, which gives them visibility into the reference. However, they don't need to own the underlying connection to use the reference in a flow — they just need to be able to run flows that use it.
The actual connection (the authenticated credential object) can be shared with other users. In the maker portal, go to Data → Connections, find the connection, click the three-dot menu, and select Share. You can grant co-owners the ability to see and use the connection. This is critical for production connections because if the original owner leaves, a co-owner can take over management.
For unattended production flows, best practice is to use a non-personal account — either a shared mailbox, a dedicated service account, or a service principal — so that the connection isn't tied to any one person's employment status.
Key insight
The most resilient production setup is: connection reference → connection owned by a service principal or service account → credentials stored and rotated in Azure Key Vault. That way no human's departure can break your production flows. See Integrating Power Automate with Azure Key Vault and Managed Identities for the full pattern.
This is the scenario that keeps platform engineers up at night: you need to rotate the password on a service account, or replace an OAuth connection because a token expired, or migrate from one SharePoint tenant to another — and you can't afford downtime.
Here's the good news: because the flow binds to the connection reference, not directly to the connection, you have some flexibility. Here are your options:
If the credential change is minor (same account, new password or refreshed token), the connection object itself may remain valid and auto-refresh. OAuth connections, for example, automatically refresh their access tokens as long as the refresh token hasn't expired. You don't need to do anything as long as the refresh token is alive.
If you need to switch accounts entirely (for example, migrating from a personal account to a service account), the process is:
The flow picks up the change immediately at the next run — no re-deployment, no edits to the flow itself.
Warning
Between the moment you remove the old connection from the reference and the moment you select the new one, any flow run that starts will fail. This window is typically just a few seconds, but for high-frequency flows, plan this update during a maintenance window or after disabling the flow's trigger temporarily.
If you're using an automated CI/CD pipeline with Azure DevOps, you can pass connection reference mappings as deployment parameters. The Power Platform Build Tools support a ConnectionReferences parameter in the import task where you specify the reference's schema name and the connection ID to map it to. This is the enterprise-grade approach — the mapping is version-controlled alongside your pipeline configuration and applied consistently on every deployment.
When you're running automated deployments, you can't click through the import wizard manually. Instead, you pass connection reference mappings via a deployment settings file or inline parameters.
The deployment settings file is a JSON file that accompanies your solution import. Here's what the relevant section looks like:
{
"ConnectionReferences": [
{
"LogicalName": "contoso_ContosoSharePointInvoiceProcessing",
"ConnectionId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline/connections/abc123def456",
"ConnectorId": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline"
},
{
"LogicalName": "contoso_ContosoOutlookNotifications",
"ConnectionId": "/providers/Microsoft.PowerApps/apis/shared_office365/connections/xyz789uvw012",
"ConnectorId": "/providers/Microsoft.PowerApps/apis/shared_office365"
}
]
}
The LogicalName is the schema name of the connection reference inside the solution — not the display name. You can find it by opening the connection reference in the solution and looking at the Name field (not the display name). The ConnectionId is the internal ID of the connection in the target environment, which you can retrieve via the Power Apps API or the maker portal URL when viewing a specific connection.
Your pipeline stores these values as environment-specific variables or secrets, and injects them at deploy time. This is the same pattern used for environment variables — one deployment artifact, environment-specific configuration injected at import.
Tip
Store connection IDs as pipeline secret variables, not plain text. Connection IDs themselves aren't credentials, but treating them as sensitive data prevents confusion and aligns with least-privilege practices.
Work through this exercise in a non-production environment. You'll need two Power Platform environments and access to SharePoint.
Objective: Create a solution with a connection reference, export it, and import it into a second environment with a different connection mapping.
Step 1: In your first environment (dev), navigate to Solutions and create a new solution called Connection Reference Practice. Set the publisher to your own publisher prefix.
Step 2: Inside the solution, add a new connection reference. Name it Practice SharePoint Connection, select the SharePoint connector, and authenticate with your current account. Save it.
Step 3: Create a new instant cloud flow inside the solution. Add a "Get items" SharePoint action. When prompted for a connection, choose the connection reference you just created rather than a direct connection. Point it at any SharePoint site and list you have access to. Save the flow.
Step 4: Export the solution as a managed solution (zip file).
Step 5: Switch to your second environment. Import the managed solution. When the import wizard reaches the connection mapping step, notice that the SharePoint reference shows as unmapped. Create a new connection (or select an existing one) in that environment. If you have a second account available, use it here to demonstrate the credential difference. Complete the import.
Step 6: After import, navigate to the solution in the second environment and turn on the flow. Manually trigger it and verify it runs successfully. Check the run history to confirm the SharePoint action used the connection you mapped, not the one from the dev environment.
Step 7 (bonus): Return to the connection reference in the second environment, remap it to a different connection, and run the flow again. Observe that the flow immediately uses the new connection without any changes to the flow itself.
Mistake: Building flows outside a solution and adding them later Flows built outside a solution use direct connections, not references. When you add the flow to a solution afterward, it may continue to use the direct connection internally. Always build inside the solution from the start.
Mistake: Using personal accounts for production connections When the person leaves or their MFA method changes, the connection breaks. Use service accounts or service principals for all production connections.
Mistake: Not verifying mappings after import The import may succeed with warnings. Always open the solution after import, check that each connection reference shows a valid (non-empty) connection, and do a test run before declaring deployment complete. You can also check whether connections are active by navigating to Data → Connections and looking for any that show "Invalid" status.
Mistake: Confusing the connection reference display name with its logical name
In CI/CD pipelines, you must use the logical/schema name (like contoso_ContosoSharePointInvoiceProcessing), not the display name. Using the display name in automation scripts will cause silent failures or mapping errors.
Mistake: Sharing the connection but not co-owning the reference If a colleague needs to maintain flows that use a reference, they need access to the reference itself (via solution co-ownership) in addition to the underlying connection. Sharing just the connection lets them run it but not manage it.
Troubleshooting: Flow turns on but fails with "Connection is not valid" Open the flow in the designer and re-save it. Sometimes a re-save forces the runtime to re-bind the flow to the current reference mapping. If that doesn't work, navigate to the connection reference, remove the connection, re-select it, save, and try again.
Troubleshooting: Import wizard doesn't show the mapping step This can happen if the solution has no connection references, or if you're importing as an unmanaged solution (which doesn't always trigger the mapping dialog the same way). Confirm your export was as a managed solution, and confirm the solution contains connection reference components by examining the solution's component list.
Note
If you're running into persistent connection issues in production and need a broader view of credential and security patterns, Securing Power Automate Flows in Production: Managing Credentials, Connection References, and Data Loss Prevention Policies covers the full governance picture including DLP interactions.
Connection references are one of those mechanisms that feel like overhead until the first time you successfully rotate a service account in production without touching a single flow. Once you've built that muscle memory — always build inside solutions, always use references instead of direct connections, always map at import time — environment promotion becomes dramatically less risky.
To recap the core ideas: a connection reference decouples your flow's logic from the specific credentials it authenticates with. The reference travels in your solution package; the actual connection stays behind in each environment. You map references to environment-appropriate connections at import time, either through the wizard UI or through a deployment settings JSON file in your CI/CD pipeline. For production, always back references with service accounts or service principals rather than personal credentials, and share co-ownership of both the reference and the underlying connection so no single person is a point of failure.
Where to go next: