WebStatic Web Appscompletefield-manual-completefield-manual-complete
Static Web Apps linked backend
A Static Web Apps linked backend is an external API service that your static front end calls through the Static Web Apps experience. Instead of using only the managed Functions that come with the app, you can connect an existing Azure Functions app, API Management service, App Service app, or Container App. Users still browse the Static Web App, but requests under the API path can be proxied to the linked backend. It is useful when the backend needs its own scale, runtime, networking, or operational ownership.
static-web-apps-linked-backend, Static Web Apps linked backend, SWA linked backend, bring your own API, Static Web Apps BYO API, Static Web Apps backend link
Difficulty
intermediate
CLI mappings
5
Last verified
2026-05-25
Microsoft Learn
Microsoft Learn describes Static Web Apps API support as integration between a static front end and backend APIs. A linked backend, also called bring your own API, connects services such as Azure Functions, API Management, App Service, or Container Apps through the Static Web Apps API path.
Technically, a linked backend belongs to the API integration layer of Azure Static Web Apps. The static front end is served by the Static Web Apps runtime, while the backend API remains a separate Azure resource with its own identity, hosting plan, logs, configuration, and lifecycle. Static Web Apps supports API routing through the /api prefix and expects one backend API type per environment. Operators manage the link through the portal or az staticwebapp backends commands, then validate route behavior, backend region requirements, authentication configuration, and plan eligibility.
Why it matters
It matters because many serious applications outgrow the default managed API pattern. A team may need an existing App Service backend, an API Management product, a Container Apps workload, or a standalone Functions app with more control over scaling and operations. Linked backends let the front end keep the Static Web Apps hosting model while the API receives dedicated ownership. Misconfiguration can break every /api call, expose a backend incorrectly, or force an unexpected SKU change. Good linked-backend design clarifies which service owns authentication, where logs live, which environment is linked, and whether the backend can handle production traffic. Validate this explicitly before changing production API routing or backend ownership.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In the Static Web Apps APIs blade, where an environment can show the backend resource currently linked for requests under the API path. during API routing validation and incident triage.
Signal 02
In Azure CLI output from az staticwebapp backends show, where operators verify the backend resource ID, environment name, and current link target. during API routing validation and incident triage.
Signal 03
In browser or API test failures for /api routes, where static pages load successfully but proxied backend calls return errors or unexpected responses. during API routing validation and incident triage.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Reuse an existing App Service or Functions API behind a Static Web Apps front end without rewriting it as managed functions.
Expose APIs through API Management policies while keeping the front-end hosting and preview workflow of Static Web Apps.
Connect a containerized backend from Azure Container Apps when the API needs custom runtime images or independent scaling.
Move a growing managed-functions API into a separately operated backend without changing the public front-end domain pattern.
Validate backend linking per environment during phased migration from a simple static site to a full-stack application.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Logistics platform links a containerized pricing API
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A freight brokerage platform hosted its customer portal on Static Web Apps but ran a containerized pricing engine that required custom libraries and independent scaling.
🎯Business/Technical Objectives
Keep the fast static customer portal unchanged.
Route pricing requests through the /api path.
Scale the pricing API separately during quote spikes.
Avoid exposing the container app directly to casual public discovery.
✅Solution Using Static Web Apps linked backend
The architecture team kept the front end in Static Web Apps and linked an Azure Container Apps backend for pricing endpoints. They validated the backend resource, linked it to the production environment, and tested quote requests through the Static Web Apps /api route. The container app retained its own scaling rules and logs, while Static Web Apps preserved the front-end deployment workflow. Route rules were reviewed so only intended pricing endpoints were available, and synthetic tests measured the full browser-to-API path. A rollback command was documented before cutover in case the backend link caused unexpected errors.
📈Results & Business Impact
Quote API capacity scaled independently from the front end during a 3.4x traffic spike.
Direct backend troubleshooting time fell by 47 percent because ownership and logs were documented.
Public portal performance stayed under a two-second page-load target while API scaling handled bursts.
No customer DNS change was needed for the pricing migration.
💡Key Takeaway for Glossary Readers
A linked backend lets Static Web Apps remain the front-end surface while a specialized API service handles heavier application logic.
Case study 02
Publisher routes partner APIs through API Management
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A digital magazine publisher needed a member portal on Static Web Apps to call subscription APIs that already lived behind Azure API Management policies.
🎯Business/Technical Objectives
Reuse existing API Management products and validation policies.
Keep the front-end publishing workflow simple for editors.
Measure partner API errors separately from static-site errors.
Avoid duplicating subscription logic in managed functions.
✅Solution Using Static Web Apps linked backend
The platform group linked the Static Web App to an API Management backend rather than rebuilding subscription endpoints. API Management kept request validation, product-level policies, and backend routing, while Static Web Apps served the editorial portal. Operators used CLI to show the linked backend and confirm the production environment before launch. They tested /api subscription-status and renewal paths from the browser, then compared API Management analytics with Static Web Apps logs. The solution separated content deployment from subscription API governance and allowed the API team to maintain policies without editing the static front end.
📈Results & Business Impact
Subscription lookup failures dropped from 6.8 percent to 1.1 percent after policy issues were isolated in API Management.
Editors published portal updates without waiting for API redeployment windows.
Partner API evidence for compliance reviews was available in one API Management report.
Duplicate endpoint code was retired, reducing maintenance effort by about 20 hours per month.
💡Key Takeaway for Glossary Readers
Linking API Management gives a Static Web Apps portal stronger API governance without sacrificing the static front-end release model.
Case study 03
Insurance portal migrates from managed functions to App Service
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
An insurance claims portal started with managed functions, then needed a larger .NET API with background dependencies, richer logging, and an existing App Service operations model.
🎯Business/Technical Objectives
Move claims APIs to a separately operated App Service.
Keep the customer-facing Static Web Apps URL pattern stable.
Validate the backend link in preview before production cutover.
Reduce emergency rollback risk during a claims-volume surge.
✅Solution Using Static Web Apps linked backend
The team deployed the new claims API to App Service and linked it first to a named Static Web Apps environment. Testers submitted claim-status and document-upload scenarios through /api paths while operations monitored App Service logs and dependency calls. After route rules and authentication headers were verified, the production Static Web App was linked to the App Service backend by resource ID. The old managed-functions folder was removed from the workflow to avoid ambiguity. A rollback plan documented how to unlink the backend and restore the previous deployment if claims submissions failed after cutover.
📈Results & Business Impact
Claims API error rate during migration stayed below 0.4 percent for the first week.
Rollback readiness time improved from an estimated four hours to 35 minutes.
API diagnostic detail increased enough to cut average claims-ticket triage by 46 percent.
Customers kept the same portal hostname and did not need new bookmarks.
💡Key Takeaway for Glossary Readers
A linked backend is a practical growth path when the API has outgrown the managed-functions model but the front end still fits Static Web Apps.
Why use Azure CLI for this?
After ten years of Azure engineering, I use Azure CLI for linked backends because API wiring is too easy to misread from a single portal screen. CLI lets me validate a backend before linking, link by resource ID, show what is currently connected, and unlink when a migration fails. That precision matters when several Function Apps, App Services, or Container Apps have similar names. CLI also helps with release automation because the backend resource ID, region, environment name, and Static Web App name can be checked in a script. For production, I want repeatable evidence that the intended backend is linked.
CLI use cases
Validate a candidate backend before linking it to a Static Web App environment.
Link a backend by resource ID so automation does not rely on ambiguous portal selections.
Show the current linked backend during troubleshooting of failing /api requests.
Unlink a backend during rollback when a migration or backend deployment breaks the application.
Check the Static Web App SKU and environment before attempting a backend link operation.
Before you run CLI
Confirm the Static Web App SKU, subscription, resource group, environment name, and backend resource ID before linking.
Check backend region requirements, especially for Azure Functions and App Service backends.
Validate that the backend type is supported and that only one backend API type is expected for the target environment.
Review authentication and route rules so /api requests are not opened more broadly than intended.
Plan rollback because linking or unlinking changes live API routing for the selected environment.
What output tells you
Validate output indicates whether the backend is eligible to link before the configuration changes production routing.
Link output confirms the backend resource ID and environment that Static Web Apps now uses for API traffic.
Show output identifies the currently linked backend, which helps separate front-end defects from backend routing defects.
Unlink output confirms API routing was detached, so requests may stop reaching the previous backend immediately.
Static Web App show output reveals SKU, default hostname, and resource ID needed to judge backend-link eligibility.
az staticwebapp backends link --name <static-app-name> --resource-group <resource-group> --backend-resource-id <backend-resource-id> --backend-region <backend-region>
az staticwebapp backendsoperateWeb
az staticwebapp backends show --name <static-app-name> --resource-group <resource-group> --output json
az staticwebapp backendsdiscoverWeb
az staticwebapp backends unlink --name <static-app-name> --resource-group <resource-group>
az staticwebapp backendsoperateWeb
az staticwebapp show --name <static-app-name> --resource-group <resource-group> --query "{sku:sku.name,hostname:defaultHostname}" --output json
az staticwebappdiscoverWeb
Architecture context
Architecturally, a linked backend turns Static Web Apps into a front-end edge with a separately operated API behind it. I use it when the backend deserves its own platform decisions: App Service for mature web APIs, API Management for policy and product exposure, Container Apps for containerized services, or Functions for event-friendly serverless APIs. The design must account for the /api route, environment-specific links, plan requirements, identity, CORS expectations, monitoring, and rollback. It is not just a convenience toggle. It is an integration contract between front-end release teams and backend service owners, and both sides need runbooks. Validate this explicitly before changing production API routing or backend ownership.
Security
Security impact is direct because a linked backend changes where API requests are accepted and how access is enforced. Review whether the backend should accept only proxied requests from the Static Web App, whether authentication is enforced by route rules, API Management policies, backend code, or a combination, and whether secrets or managed identities are used downstream. Do not link a backend that still trusts broad public access unless that exposure is intentional. Validate role requirements for /api routes, backend authorization, TLS, and logging. A mistaken link can make a private service reachable through a public front end. Validate this explicitly before changing production API routing or backend ownership.
Cost
Cost impact is direct and indirect. A linked backend may require Standard or Dedicated Static Web Apps capabilities and it definitely brings the backend service's own billing model: App Service plans, Functions execution or plans, Container Apps consumption, API Management tiers, logging, and downstream data services. Linking does not make those costs disappear behind Static Web Apps. It can also increase monitoring and support effort because two services now explain one user journey. FinOps review should identify the backend owner, expected request volume, logging retention, idle capacity, and whether a cheaper managed-functions pattern would meet the requirement. Validate this explicitly before changing production API routing or backend ownership.
Reliability
Reliability impact is direct because the front end now depends on a separate backend resource. A Static Web App can serve static assets while every /api request fails because the linked backend is unhealthy, scaled down, misconfigured, or in the wrong environment. Operators need health checks, backend logs, route tests, and rollback steps for unlinking or relinking. Linked backends also change blast radius: a backend deployment can break the web app without changing the front-end artifact. Reliable designs test production and preview links separately, document ownership, and monitor both Static Web Apps and the backend service together. Validate this explicitly before changing production API routing or backend ownership.
Performance
Performance impact is direct for API calls. Static assets may still load quickly, but /api requests now depend on backend cold start, plan capacity, container scaling, API Management policy overhead, network path, and backend region. Route rules and authentication can add processing, and misaligned environments can send testers to slower nonproduction services. Operators should measure end-to-end browser timing, backend latency, error rate, and scale behavior under realistic traffic. A linked backend can improve performance when it gives the API dedicated resources, but it can also introduce bottlenecks if the backend is underprovisioned. Validate this explicitly before changing production API routing or backend ownership.
Operations
Operators manage linked backends by validating eligibility, linking with the correct resource ID, confirming the environment name, testing /api routes, and tracking backend ownership. Practical troubleshooting includes checking the Static Web App environment, the backend resource health, backend region where required, route rules, authentication headers, and logs from both services. During migrations, operators should record the previous backend, link target, validation result, and rollback command. Because only one backend type is available to a single environment, change planning matters. Operations should treat the link as production integration, not a casual front-end setting. Validate this explicitly before changing production API routing or backend ownership.
Common mistakes
Linking the wrong backend resource because several Function Apps or App Services have nearly identical names.
Forgetting that /api requests depend on backend health even when static page delivery looks normal.
Trying to use multiple backend API types in the same environment without understanding the one-backend constraint.
Skipping route and authentication review, which can make backend endpoints reachable through an unexpected front-end path.
Testing the production environment while the backend was linked only to a preview or named environment.