Connect to Azure and external services
Builder application code can integrate with a separately provisioned service when the app can reach its endpoint and authenticate with the required permissions. Builder does not automatically create databases, caches, storage accounts, service connections, or private networking.
Prerequisites
- An existing development/test Builder App; connections that use private credentials need a server-side component.
- A separately provisioned development/test dependency with its supported SDK/API, endpoint, credentials, and required data permissions.
- Confirmed network reachability from the app without weakening the service's existing restrictions.
Connection checklist
- Choose a development/test dependency. Confirm its API, endpoint, pricing, and ownership.
- Verify reachability. Check DNS, TLS, destination firewall rules, and the selected preview target. A private endpoint does not provide Builder with a route to it.
- Choose credentials. Prefer the app's managed identity when the service supports Microsoft Entra authentication; otherwise use the service's server-side credential. Scope permissions narrowly.
- Grant data permissions. Assign only the operations the app needs at the narrowest service scope. Azure resource management access and data access are different permissions.
- Configure and deploy. Save endpoint/settings as variables, then build and deploy a new version.
- Verify an operation from the app. Test a bounded read before enabling writes. Capture sanitized failure status without tokens or data dumps.
Version variables require a new version to capture current values. Retained-version activation uses historical variables, so it can restore an old endpoint or credential.
Azure integrations
These are examples, not an exhaustive list. Your app can also connect to other Azure and external services using their supported SDKs or APIs, provided network access, authentication, and permissions allow it. These are connections you configure in your app, not Builder-managed integrations.
| Dependency | Application pattern |
|---|---|
| Cosmos DB for NoSQL | Use a server-side SDK and managed identity or database permissions; see the Cosmos DB example below |
| Blob Storage | Use its SDK, managed identity, and a scoped blob data role; see storage guidance |
| Key Vault | Application code uses the vault SDK with secret-read permission and a reachable vault; automatic keyVaultReference variable resolution is not supported |
| Model or other Azure API | Use the service's documented identity/API contract and verify the endpoint and access on the selected target |
Check the destination's authentication requirements. Credentials belong in server-side code, not static browser assets. For Key Vault, follow application access guidance.
Cosmos DB example
Record the account endpoint, database name, and container name for your separately provisioned test database. Keep its network restrictions intact; a private endpoint does not connect Builder to that network. See networking.
With a managed identity, a read-only app needs Cosmos DB Built-in Data Reader at the required database/container scope, assigned to the identity's principal ID. An Azure Reader or Contributor management role does not grant item-read access. See Cosmos DB role-based access.
If the account allows key-based access, follow Cosmos DB SDK guidance and keep the key server-side; never expose an account key in a static frontend. Verify a small test read before enabling writes, and report a safe success or failure result rather than complete database items or credentials. Check database permissions and network reachability separately when diagnosing errors. Cosmos DB has its own charges, backup, and retention settings.
External APIs
Keep credentials in the backend and use HTTPS to a trusted, configured destination. Do not let a user-supplied URL turn your backend into an unrestricted proxy. Use request deadlines, bounded retries for appropriate transient errors, and explicit failure handling. Avoid silently returning a successful-looking result when a dependency failed.
For a static frontend, calls originate in the user's browser; the API must support its origin and caller authentication. Never embed a private API key into a frontend build. See networking for the browser/server distinction.
Diagnose failures
| Symptom | Check |
|---|---|
| DNS error or timeout | Endpoint, destination networking, DNS, and target reachability |
| HTTP 401 | Chosen identity/credential, token audience, and credential validity |
| HTTP 403 | Data-plane permissions and destination firewall restrictions |
| Old endpoint/value after saving | New version capture and the active deployment |
| SDK works locally but fails in Builder | Check the credentials actually used by the deployed app and its network access |
Separate these checks rather than widening permissions or opening a firewall indiscriminately. Logging and monitoring explains available diagnostics.
Clean up test dependencies
Remove only the test data, credentials, role assignments, and resources you created for this exercise when you no longer need them. Preserve services and data that your app reused. Deleting a Builder App does not delete its separately owned dependencies or stop their charges.