> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/build/integration-overview/azure/azure-api.md).

# Azure Subscriptions Integration

Query your Azure subscriptions in natural language — resources, costs, and Advisor recommendations — through a Microsoft Entra app registration you control

Connect your Azure subscriptions and ask Darcy about your cloud the way you'd ask a colleague. "Which virtual machines are running in West Europe?" "What did we spend by service this month?" "What is Advisor telling us about reliability?" Darcy queries Azure Resource Manager live — no exports, no dashboards to build.

{% hint style="success" %}
**From question to answer**: Ask *"list every resource without tags, grouped by resource group"* and Darcy runs a single Azure Resource Graph query across all of your connected subscriptions and regions at once, then hands you the list.
{% endhint %}

## Overview

The integration talks to **Azure Resource Manager (ARM)**, the same API the Azure portal and CLI use. That means anything in ARM is reachable, not just a curated subset — and what Darcy may actually do is decided by the Azure role you assign to the app registration.

| Mode                    | What it does                                                            |
| ----------------------- | ----------------------------------------------------------------------- |
| **Discover services**   | Lists the Azure resource providers registered in a subscription         |
| **Discover operations** | Lists the resource types, API versions, and operations for one provider |
| **Discover resources**  | Queries what you actually have, using Azure Resource Graph (KQL)        |
| **Execute**             | Calls any ARM operation by method and path                              |

Darcy picks the mode for you. You ask a question; it discovers the right provider, resolves the API version, and runs the query.

## Key Features

### Resource Intelligence

* **Cross-subscription in one query** — Resource Graph spans every allowed subscription and every region at once, so there's no per-region fan-out and no missed resources
* **Automatic API versioning** — every ARM call needs an `api-version` and each resource type has its own. Darcy resolves the newest stable version on its own, and only uses a specific one when a preview feature requires it
* **Full resource detail on demand** — when a summary isn't enough, Darcy reads a single resource's complete properties

### Cost Analysis

Cost Management queries work on a **read-only** integration — they're `POST` requests, but the integration classifies them as reads. They need `Cost Management Reader` or higher on the scope being queried.

| Question                                     | What Darcy queries                                 |
| -------------------------------------------- | -------------------------------------------------- |
| "What have we spent this month, by service?" | Month-to-date actual cost, grouped by service name |
| "Show me the daily trend for January"        | Daily granularity over a custom period             |
| "Which resource groups cost the most?"       | Last month's cost, grouped by resource group       |
| "How does spend break down by region?"       | Actual cost grouped by location                    |

### Recommendations

Azure Advisor recommendations are available through the same path, so cost, security, reliability, performance, and operational-excellence findings can be pulled into a conversation, a report, or a workflow.

## Security Architecture

### Microsoft Entra App Registration

Access runs through an app registration in **your** Entra tenant. You create it, you assign its roles, and you can revoke or rotate it without involving DarcyIQ.

### Your Azure Role Is the Boundary

| You assign                               | Darcy can                                                                                    |
| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Reader**                               | Read resources and configuration. Every write comes back from Azure as `AuthorizationFailed` |
| **Cost Management Reader** (with Reader) | Everything above, plus spend analysis                                                        |
| **Contributor**                          | Create, update, and delete resources                                                         |

{% hint style="warning" %}
**There is no DarcyIQ switch that grants write access.** Permission comes from the Azure role assignment and nowhere else. If a write is refused, Darcy reports Azure's refusal as-is rather than retrying or looking for another route — the fix is a role change in Azure, which only you can make.
{% endhint %}

### Additional Protections

| Protection                  | Behavior                                                                                                                                                                         |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscription allow-list** | Only the subscription IDs you list are reachable. A request naming any other subscription is refused before a call is made                                                       |
| **No credential retrieval** | `listKeys`, `listSecrets`, and `listConnectionStrings` are always refused, whatever the role — their responses are reusable secrets. Use the Azure portal or CLI if you need one |
| **Secret stored encrypted** | The client secret is write-only from the UI's perspective; it is never returned                                                                                                  |
| **Expiry warnings**         | Record the secret's expiry date and DarcyIQ warns you before it lapses                                                                                                           |
| **Connection test**         | Test the integration when you save it, and see its health in your integrations list                                                                                              |

## Setup Process

### Prerequisites

1. Permission to create an app registration in Microsoft Entra ID
2. Permission to assign roles on each subscription you want to connect
3. The subscription IDs you intend to connect

### Step-by-Step Configuration

{% stepper %}
{% step %}
**Create the app registration** In the Azure portal, go to **Microsoft Entra ID → App registrations → New registration**.
{% endstep %}

{% step %}
**Copy the tenant and client IDs** From the app's **Overview** page, copy the **Directory (tenant) ID** and the **Application (client) ID**.
{% endstep %}

{% step %}
**Create a client secret** Under **Certificates & secrets**, create a new client secret and copy its value immediately — Azure shows it only once. Note its expiry date while you're there.
{% endstep %}

{% step %}
**Assign a role on each subscription** For each subscription, go to **Subscriptions → Access control (IAM) → Add role assignment** and assign the app the **Reader** role. Add **Cost Management Reader** if you want spend analysis, and only assign **Contributor** if you want Darcy to make changes.
{% endstep %}

{% step %}
**Add the integration in DarcyIQ** Open your integrations, choose **Azure API Integration**, and fill in the fields below. Test the connection before saving.
{% endstep %}
{% endstepper %}

### Configuration Fields

| Field                       | Required | Notes                                                                           |
| --------------------------- | -------- | ------------------------------------------------------------------------------- |
| **Azure Integration Name**  | Yes      | How this connection is identified throughout DarcyIQ. Must be unique            |
| **Directory (Tenant) ID**   | Yes      | The Entra tenant that owns the app registration                                 |
| **Application (Client) ID** | Yes      | From the app registration's Overview page                                       |
| **Client Secret**           | Yes      | The secret value from Certificates & secrets                                    |
| **Azure Subscription IDs**  | Yes      | Comma-separated list of the subscriptions the app has a role assignment on      |
| **Default Subscription**    | No       | Used when a request doesn't name one. Defaults to the first subscription listed |
| **Client Secret Expiry**    | No       | `YYYY-MM-DD`. DarcyIQ warns you before the secret lapses                        |

### Organization or Personal

The Azure integration can be configured at **organization** scope, so everyone in your organization shares one connection, or at **user** scope, for a connection only you use. See [Integration Settings](/settings-and-configuration/integration.md).

## Using the Integration

### Asking Questions

Once connected, Azure is available in [Chat](/core-features/darcy-chat.md), to [Agents](/core-features/agents.md), and inside [Workflows](/build/ai-workflows.md) and scheduled runs.

| You ask                                     | What happens                                                                   |
| ------------------------------------------- | ------------------------------------------------------------------------------ |
| "What VMs do we have and how big are they?" | A Resource Graph query returns names, resource groups, locations, and VM sizes |
| "Count resources by type and location"      | A single summarizing query across all subscriptions                            |
| "Find anything untagged"                    | Resources with no tags, projected to name, type, and resource group            |
| "What's in the production resource group?"  | A direct ARM read of that resource group's contents                            |
| "What does Advisor recommend?"              | Advisor recommendations for the subscription                                   |
| "Spend by service, month to date"           | A Cost Management query aggregated by service name                             |

### Multiple Subscriptions

Resource Graph searches **every** allowed subscription unless you name one. Direct ARM calls use the subscription in the path, or your default subscription when none is given. Naming a subscription outside the allow-list is refused rather than silently redirected.

### Large Result Sets

Resource discovery is paginated. When more results exist, Darcy tells you and asks whether to keep going rather than pulling thousands of rows you didn't ask for.

## Limitations and Considerations

| Consideration                      | Detail                                                                                                                                  |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Writes depend on your role**     | Most connections are `Reader`, so writes fail at Azure. This is by design                                                               |
| **No secret retrieval**            | Key- and secret-listing operations are always refused                                                                                   |
| **Cost data needs its own role**   | Spend questions require `Cost Management Reader` on the scope being queried                                                             |
| **Client secrets expire**          | Rotate before the expiry date, or the integration stops working                                                                         |
| **Preview features**               | Occasionally need a specific API version; Darcy falls back to discovery when a call reports an unregistered provider or invalid version |
| **Subscription scope is explicit** | New subscriptions don't appear automatically — add the ID and assign the role                                                           |

## Best Practices

| Practice                                    | Recommendation                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Start read-only**                         | Connect with `Reader` and live with it for a while before considering `Contributor`               |
| **Connect one subscription first**          | Validate the setup on a non-production subscription, then add the rest                            |
| **Add Cost Management Reader deliberately** | It's the difference between "what do we have" and "what does it cost"                             |
| **Record the secret expiry**                | It costs one field and turns a silent outage into a warning                                       |
| **Tag your resources**                      | Tag-based questions are only as good as your tagging; Darcy will happily show you what's untagged |
| **Use groups for access**                   | Manage who can reach the integration through [Groups](/settings-and-configuration/groups.md)      |

## Next Steps

| Goal                                            | Documentation                                                          |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| See the wider Azure picture                     | [Azure Ecosystem](/build/integration-overview/azure.md)                |
| Do the same for AWS                             | [AWS Accounts Integration](/build/integration-overview/aws/aws-api.md) |
| Restrict which tools agents may use             | [Tool Permissions](/build/integration-overview/tool-permissions.md)    |
| Configure organization vs personal integrations | [Integration Settings](/settings-and-configuration/integration.md)     |
| Put cloud questions on a schedule               | [Events & Scheduling Agents](/build/automations.md)                    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.darcyiq.com/build/integration-overview/azure/azure-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.