Skip to main content

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.

​
Table of Contents

​
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:
MethodBest ForRequires Admin Consent?Token Refresh
OAuthOrganizations with Azure AD admin consent grantedYesAutomatic
API KeyIndividual users or orgs where admin consent is not availableNoNot required (keys don’t expire)

​
Azure Setup

​
Create an Azure AI Foundry Project

  1. Go to Azure AI Foundry 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 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: 
    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
  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
  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.

​
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 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 for where to find it: 
    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 for where to find it: 
    https://your-project-name.region.inference.ml.azure.com
  4. Enter your API Key — same place as the Endpoint URL, see 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 or 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
  2. Use the API Key connection method 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 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)
  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