How to use API Key in Azure AI Foundry

Question

How to utilize Azure AI Foundry's API Key? The official SDK azure-ai-projects for some reason doesn't support API Credential and there is no documentation how to use the API key with REST. On top of that, using DefaultAzureCredentials requires the user to have a Azure AI User role to manipulate agents . It's a whole mess, I just want to use API key and access Azure AI Foundry features.

Answer 1

You're right — Azure AI Foundry is a bit of a mess at this point from the auth standopoint because there are two different “planes” with different auth requirements:

• Control plane (projects / agents management / SDK azure-ai-projects) — this is management of projects and agents. Microsoft's SDKs and the Projects REST surface generally require Microsoft Entra (Azure AD) tokens and RBAC (e.g. Azure AI User / project roles). You can't use a plain API key to create/edit agents in many places.
• Data plane (model/runtime endpoints like Responses / OpenAI-like APIs / inference) — these can accept API keys (or other resource keys) depending on the specific endpoint. That's where you can usually use an API key to run chat/responses/completions.

So effectively, if you only want to call models / run a chat / call Responses -> call the data-plane endpoint (Responses / OpenAI models) directly and send the API key in the expected header (examples below). This works with API keys. If you want to create or change agents or projects -> the Projects/Agents management APIs (and the azure-ai-projects SDK) expect Azure AD authentication and RBAC. API key won't let you manage agents. You must use DefaultAzureCredential / service principal or a user with the Azure AI User role.

Regarding the usage of API key with REST, there are a couple of header formats Microsoft uses across AI services.

• api-key: <your-key> — commonly used by Azure OpenAI-style Responses endpoints.
• Ocp-Apim-Subscription-Key: <your-key> — older/other Azure AI “resource key” header seen in some AI Foundry docs (multi-service resource keys).

Make sure to check the exact endpoint docs you're calling (Responses vs Projects vs OpenAI) — they list which header to use and which query param api-version is required. The following examples assume the project's Responses (runtime) endpoint.

Calling Responses API with curl (API key) - replace PROJECT_ENDPOINT with the project endpoint from Foundry Studio (Overview page) and API_KEY with your key. Also adjust api-version per the doc.

curl -X POST "https://<your-project-endpoint>/responses?api-version=2024-12-01-preview" \
  -H "Content-Type: application/json" \
  -H "api-key: <API_KEY>" \
  -d '{
    "kind": "chat",
    "input": {
      "messages": [
        {"role": "user", "content": "Hello from curl"}
      ]
    }
  }'

If the endpoint expects Ocp-Apim-Subscription-Key instead, swap the header name:

-H "Ocp-Apim-Subscription-Key: <API_KEY>"

Always check the endpoint's exact header requirement since different Foundry surfaces historically used either header names.

Python (requests) — Responses with api-key

import requests, json

url = "https://<your-project-endpoint>/responses?api-version=2024-12-01-preview"
headers = {
    "Content-Type": "application/json",
    "api-key": "<API_KEY>",
}
body = {
    "kind": "chat",
    "input": {
        "messages": [
            {"role": "user", "content": "Hello from Python"}
        ]
    }
}

r = requests.post(url, headers=headers, json=body)
print(r.status_code, r.text)

If the endpoint wants Ocp-Apim-Subscription-Key, put that into headers instead.

As you pointed out, azure-ai-projects SDK/DefaultAzureCredential wants Azure AD and RBAC because azure-ai-projects is the Projects (control plane) SDK — it's designed to manage and enumerate projects, create agents, configure tools, etc. For security and auditability Microsoft requires Azure AD auth + RBAC for these management operations. That's why the SDK examples show DefaultAzureCredential() (or AzureKeyCredential for some cases) and you see the requirement for Azure AI User role to manipulate agents. If you only have an API key, you can't do these management tasks through that SDK.

As far as workarounds go, you might consider the following:

Option 1 — split duties: Use API key for runtime, Azure AD for management

• Runtime usage (chat/completions/responses) — use the API key + direct REST to the Responses or model endpoint; that covers inference and runtime agent invocations.
• Agent / project management — create a service principal (app registration) and assign the minimal RBAC role (Azure AI User / project contributor) to that principal so your automation can call the management APIs using a token (client credential flow). That avoids using an interactive user and satisfies the SDK's expectations. For example:

    az ad sp create-for-rbac --name "foundry-mgmt-sp" --role "Azure AI User" --scopes /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.AIFoundry/...
  

  Then use az account get-access-token --resource https://cognitiveservices.azure.com or SDK ClientSecretCredential to get a token.

Option 2 — use API Management or an API gateway in front of Foundry (if you must expose only API-key auth)

If your policy requires only key-based clients, put Azure API Management (or another gateway) in front of Foundry: the gateway accepts your API key and then calls Foundry with the appropriate credentials (or forwards the key to the right header). People use this to centralize keys and rate-limit. There are guides and community posts showing how to import Foundry APIs into APIM.

Option 3 — tool connections and authorization header mapping (agents calling external APIs)

If you're building agents that call external APIs, Foundry's tool/connection mapping can be finicky. If you want an agent to send Authorization: Bearer <token> to an external tool, you must ensure the connection key name maps to the header name expected by the target. Foundry's OpenAPI tooling expects you to declare a connection key (e.g., “BearerAuth”) and then provide a connection where the value is Authorization: Bearer <token>. If it looks like the token is missing, check the tool's security scheme mapping and the connection key name. (This is a common gotcha.)

More at https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/develop/sdk-overview, https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/responses, https://learn.microsoft.com/en-us/azure/ai-foundry/openai/reference, https://learn.microsoft.com/en-us/azure/ai-services/authentication, https://learn.microsoft.com/en-us/azure/ai-foundry/openai/latest

---

If the above response helps answer your question, remember to "Accept Answer" so that others in the community facing similar issues can easily find the solution. Your contribution is highly appreciated.

hth

Marcin