> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4minds.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Foundry

## Table of Contents

* [Overview](#overview)
* [Azure Setup](#azure-setup)
  * [Create an Azure AI Foundry Project](#create-an-azure-ai-foundry-project)
  * [Deploy a Model](#deploy-a-model)
  * [Find Your Credentials](#find-your-credentials)
  * [Grant Azure RBAC Role (Required for OAuth)](#grant-azure-rbac-role-required-for-oauth)
  * [OAuth App Registration (Admin)](#oauth-app-registration-admin)
* [Connecting to 4MINDS](#connecting-to-4MINDS)
  * [Method 1: OAuth (Recommended)](#method-1-oauth-recommended)
  * [Method 2: API Key](#method-2-api-key)
* [Creating an External Model](#creating-an-external-model-with-microsoft-foundry)
  * [Guide Me (Easy Mode)](#guide-me-easy-mode)
  * [Advanced Mode](#advanced-mode)
* [Using Foundry Models](#using-foundry-models)
  * [Browsing Deployments](#browsing-deployments)
  * [Chat Completions](#chat-completions)
* [Troubleshooting](#troubleshooting)

***

## Overview

The Microsoft Foundry integration connects your Azure AI Foundry project to the 4MINDS platform, allowing you to:

* **Browse deployments** from your Azure AI Foundry project
* **Register models** deployed in Foundry as 4MINDS models
* **Run chat completions** against Foundry-hosted models (GPT-4o, GPT-4, Llama, Mistral, etc.)
* **Fine-tune models** using 4MINDS datasets with Foundry compute

Two authentication methods are supported:

| Method      | Best For                                                      | Requires Admin Consent? | Token Refresh                    |
| ----------- | ------------------------------------------------------------- | ----------------------- | -------------------------------- |
| **OAuth**   | Organizations with Azure AD admin consent granted             | Yes                     | Automatic                        |
| **API Key** | Individual users or orgs where admin consent is not available | No                      | Not required (keys don't expire) |

***

## Azure Setup

### Create an Azure AI Foundry Project

1. Go to [Azure AI Foundry](https://ai.azure.com) and sign in with your Microsoft account
2. Click **+ New project**
3. Select or create an **Azure AI hub** resource
4. Give your project a name and select a region
5. Click **Create project**

> **Tip:** Choose a region close to your users for lower latency. Models available vary by region.

### Deploy a Model

Before connecting to 4MINDS, deploy at least one model in your Foundry project:

1. In your Azure AI Foundry project, go to **Model catalog** in the left sidebar
2. Browse or search for a model (e.g., `gpt-4o`, `gpt-4`, `Mistral-large`)
3. Click **Deploy**
4. Choose a deployment name and configure settings:
   * **Deployment name**: A unique identifier (e.g., `gpt-4o`)
   * **Model version**: Select the desired version
   * **Deployment type**: Standard or Provisioned
   * **Rate limits**: Configure tokens-per-minute as needed
5. Click **Deploy**

### Find Your Credentials

Both the endpoint URL and API key live in the same place. The steps below show you how to find each of them.

#### Option A: From Azure AI Foundry (ai.azure.com) — Easiest

1. Go to [Azure AI Foundry](https://ai.azure.com) and sign in
2. Click on your project/resource
3. On the **Overview** page you'll see:
   * **Microsoft Foundry project endpoint** — copy this URL
   * **API Key** — click the copy icon to copy it
4. The endpoint URL looks like:
   ```text theme={null}
   https://your-project-name.region.inference.ml.azure.com
   ```

#### Option B: From Azure Portal (portal.azure.com)

1. Open your project in [Azure AI Foundry](https://ai.azure.com)
2. In the left sidebar, go to **Resource Management > Keys and Endpoint**
3. Copy the **Endpoint** URL
4. Under **Keys**, you'll see **Key 1** and **Key 2** — click the copy icon next to either key

> **Important:** Copy the full endpoint URL including `https://`. Do not include a trailing slash — 4MINDS will strip it, but it's cleaner to paste it correctly.

> **Security:** Treat your API key like a password. Do not share it or commit it to source control. You can regenerate keys at any time — regenerating a key immediately invalidates the old one.

> **Tip:** Azure provides two keys so you can rotate them without downtime. Use Key 1 for your connection, and if you need to rotate, switch to Key 2 before regenerating Key 1.

### Grant Azure RBAC Role (Required for OAuth)

When connecting via **OAuth**, your Azure user account needs an RBAC role on the Foundry resource to list deployments and invoke models. The API Key method bypasses this because the key itself carries the permissions.

1. Open your Foundry resource in [Azure Portal](https://portal.azure.com)
2. In the left sidebar, click **Access control (IAM)**
3. Click **+ Add > Add role assignment**
4. Assign one of the following roles to your user account (or an Azure AD group you belong to):
   * **Azure AI Developer** — recommended; grants access to Foundry data plane APIs
   * **Cognitive Services Contributor** — broader alternative
5. Click **Review + assign**

> **Note:** Azure RBAC changes can take up to a minute to propagate. If your first connection attempt fails with a permissions error, wait 30–60 seconds and try again. See [Troubleshooting](#permissions-still-propagating-after-oauth-connect).

### OAuth App Registration (Admin)

If your organization wants to use the OAuth connection method, an Azure AD administrator must register and consent to the 4MINDS application:

1. Navigate to **Azure Portal > Microsoft Entra ID > App registrations**
2. Find the 4MINDS Foundry app registration (or create one if self-hosting)
3. Go to **API permissions**
4. Ensure the following permissions are configured:
   * `https://ai.azure.com/.default` — Access Azure AI services on behalf of the signed-in user (covers all delegated permissions needed by Foundry)
   * `offline_access` — Issue a refresh token so 4MINDS can refresh the access token without re-prompting
5. Click **Grant admin consent for \[Your Organization]**
6. Confirm the consent prompt

> **Note:** If you see "Admin approval required" or "AADSTS65001" when trying to connect via OAuth, your Azure AD admin has not yet granted consent. Use the [API Key method](#method-2-api-key) as an alternative.

***

## Connecting to 4MINDS

### Method 1: OAuth (Recommended)

OAuth signs you in with your Microsoft account and automatically refreshes access tokens 5 minutes before they expire, so long-running sessions don't break. Connecting is a two-step process: authorize Microsoft, then provide the Foundry endpoint URL.

**Steps:**

1. Open **Integrations** from the main navigation in 4MINDS and select **Microsoft Foundry** (or do this during onboarding)
2. Make sure the **OAuth** tab is selected (it is selected by default)
3. Click **Connect with Microsoft**
4. A Microsoft login popup will open — sign in with your Azure account and grant the requested permissions
   * If the popup is blocked, enable popups for the site and try again
5. After successful authentication, the popup closes automatically and 4MINDS shows an "OAuth connection successful" message
6. **Enter your Endpoint URL** — see [Find Your Credentials](#find-your-credentials) for where to find it:
   ```text theme={null}
   https://your-project-name.region.inference.ml.azure.com
   ```
7. Click **Save Endpoint URL**

Your Foundry deployments will load automatically once the endpoint URL is saved. The endpoint URL is preserved if you later disconnect and reconnect via OAuth.

> **Note:** The OAuth popup may close before the backend finishes exchanging the authorization code. 4MINDS polls the connection status for several seconds afterward, so give it a moment if the success state doesn't appear instantly.

### Method 2: API Key

Use the API Key method when:

* Your organization's Azure AD admin has not granted consent for OAuth
* You prefer not to use OAuth
* You're connecting from a personal Azure account without organizational admin access

Unlike OAuth, the API Key method takes the endpoint URL and key together in a single step and stores them as an `api_key` connection.

**Steps:**

1. Open **Integrations** from the main navigation in 4MINDS and select **Microsoft Foundry** (or do this during onboarding)
2. Click the **API Key** tab
3. Enter your **Endpoint URL** — see [Find Your Credentials](#find-your-credentials) for where to find it:
   ```text theme={null}
   https://your-project-name.region.inference.ml.azure.com
   ```
4. Enter your **API Key** — same place as the Endpoint URL, see [Find Your Credentials](#find-your-credentials)
5. Click **Connect**
6. 4MINDS tests the connection against the Foundry endpoint and saves your credentials if successful

> **Note:** API keys do not expire automatically, but they can be regenerated by anyone with access to the Azure AI Foundry project settings. If your connection stops working with a 401 error, check that your key hasn't been regenerated — and reconnect with the new key.

> **Tip:** The API Key method skips the Azure RBAC role requirement because the key itself carries the permissions needed to call Foundry endpoints.

***

## Creating an External Model with Microsoft Foundry

There are two ways to create a model backed by a Microsoft Foundry deployment: **Guide Me** (easy mode) and **Advanced** mode.

### Guide Me (Easy Mode)

1. From the home screen, click **Guide Me**
2. On the **Model Source** step, you'll see two options:
   * "Build custom AI"
   * A list of external model providers
3. Select **Microsoft Foundry** from the list of providers
4. Connect to your Foundry account using either [OAuth](#method-1-oauth-recommended) or [API Key](#method-2-api-key)
5. Once connected, you'll see a list of your deployed models — select the one you want to use
6. Click **Next** to proceed to the **Upload Data** step

### Advanced Mode

1. Navigate to the **Models** page
2. Click the **Create Model** button
3. Enter a **model name**
4. Under **Or connect an external model**, select **Microsoft Foundry**
5. Connect to your Foundry account if not already connected
6. Select a deployed model from the list
7. Click **Next** to proceed to the **Upload Data** step

***

## Using Foundry Models

### Browsing Deployments

Once connected, your Foundry deployments appear automatically:

* Each deployment shows its **name**, **model type**, and **status**
* Click on a deployment to select it

### Chat Completions

Registered Foundry models can be used anywhere in 4MINDS that supports model selection:

* Chat conversations
* Model comparison
* Fine-tuning evaluation

Chat completions are routed through the Azure OpenAI-compatible endpoint (`/openai/deployments/{deployment}/chat/completions`) on your Foundry project, with streaming supported via server-sent events.

***

## Troubleshooting

### "Admin approval required" when connecting via OAuth

**Cause:** Your Azure AD tenant requires admin consent for the 4MINDS application.

**Solutions:**

1. Ask your Azure AD administrator to [grant admin consent](#oauth-app-registration-admin)
2. Use the [API Key connection method](#method-2-api-key) instead — no admin consent required

### "Invalid credentials" or "Connection test failed" (API Key)

**Cause:** The endpoint URL or API key is incorrect.

**Solutions:**

1. Verify the endpoint URL is copied exactly from Azure AI Foundry (including `https://`, no trailing slash)
2. Re-copy the API key from Azure AI Foundry > **Overview** or **Keys and Endpoint**
3. Check that the API key hasn't been regenerated since you last copied it
4. If your key was rotated, reconnect with the new key

### "No deployments found"

**Cause:** No models are deployed in the Foundry project, or the endpoint URL points to the wrong project.

**Solutions:**

1. Verify you have at least one [deployed model](#deploy-a-model) in your Azure AI Foundry project
2. Check that the endpoint URL matches the correct project
3. Ensure the deployed model's status is "Succeeded" in Azure AI Foundry

### Permissions still propagating after OAuth connect

**Cause:** Azure RBAC role assignments can take up to a minute to propagate after you grant them.

**Solutions:**

1. Wait 30–60 seconds and retry — 4MINDS automatically retries deployment listing once on auth failures, but if the delay is longer you may need to refresh the page
2. Confirm you have the **Azure AI Developer** or **Cognitive Services Contributor** role on the Foundry resource (see [Grant Azure RBAC Role](#grant-azure-rbac-role-required-for-oauth))
3. If the error persists past a minute, try disconnecting and reconnecting

### OAuth token refresh failed

**Cause:** The OAuth refresh token has expired or been revoked. Refresh tokens are long-lived but can be invalidated by password changes, conditional access policy updates, or admin revocation.

**Solutions:**

1. Disconnect and reconnect via OAuth
2. Check that admin consent is still granted in Azure AD
3. Switch to API Key method if the issue persists

> **Note:** This error only applies to OAuth connections. API Key connections do not use refresh tokens and are unaffected.

### Connection works but chat completions fail

**Cause:** The selected deployment may have rate limits, be in a failed state, or the model may not support the requested operation.

**Solutions:**

1. Check the deployment status in Azure AI Foundry — ensure it shows "Succeeded"
2. Verify rate limits haven't been exceeded (check Azure portal for 429 errors)
3. Ensure the deployment supports chat completions (some models only support embeddings or completions)
4. Try a different deployment to isolate the issue

### OAuth popup closes but 4MINDS shows "Authentication cancelled or failed"

**Cause:** The popup closed before the backend finished exchanging the authorization code with Microsoft, or the popup was blocked.

**Solutions:**

1. Enable popups for the 4MINDS site in your browser settings
2. On Safari: **Safari > Settings > Websites > Pop-up Windows** and allow popups for 4MINDS
3. Wait a few seconds — 4MINDS polls for connection status after the popup closes and may still recover
4. If it persists, click **Connect with Microsoft** again