Azure OpenAI setup
Connect Port to OpenAI models hosted in your Azure OpenAI deployment. This guide walks you through storing your Azure OpenAI credentials and registering Azure OpenAI as an LLM provider in Port.
Prerequisites
- An active Azure subscription with Azure OpenAI Service enabled.
- An Azure OpenAI deployment with the models you want to use. You can create deployments in the Azure OpenAI Studio.
- Your Azure OpenAI API key and resource name.
Step 1: Gather your Azure OpenAI configuration
Before configuring the provider, collect the following information from your Azure OpenAI deployment:
- Resource name: The name of your Azure OpenAI resource. For an endpoint such as
https://your-resource-name.openai.azure.com, use onlyyour-resource-name. - API key: Your Azure OpenAI API key. You can find this in the Azure portal under your Azure OpenAI resource's Keys and Endpoint section.
- Model deployments: The deployment name for each model you want to use, as shown in Azure OpenAI Studio.
Deployment naming
By default, each Azure deployment name must match the Port model ID, for example gpt-5. If you use a different deployment name, map the Port model ID to that name with config.modelDeployments, for example "modelDeployments": {"gpt-5": "my-gpt-5-deployment"}. You only need this mapping for deployment names that differ from the model IDs.
Step 2: Store your API key in Port secrets
Store your Azure OpenAI API key in Port's secrets system.
- Open the Credentials modal.
- Click on the
Secretstab. - Click on
+ Secretand add your secret(s).
For provider-specific secret requirements and examples, see Step 2: Store API Keys in Secrets.
You can choose any names for your secrets. The examples are suggestions. Use names that make sense for your organization, and reference the exact names in your provider configuration.
For more details on managing secrets, see the Port Secrets documentation.
Step 3: Register Azure OpenAI with the Port API
Call the create or connect an LLM provider API with validate_connection=true to test your configuration. Set provider to "azure-openai" and provide your Azure OpenAI resource name and the secret name you created in Step 2.
Use the following fields in config:
| Field | Required | Description |
|---|---|---|
apiKeySecretName | Yes | The name of the Port secret containing your Azure OpenAI API key. |
resourceName | Yes | Your Azure OpenAI resource name, without the URL scheme or domain suffix. |
modelDeployments | No | A mapping from Port model IDs to Azure deployment names. Only needed when the names differ. |
The following example assumes you have matching deployments for all supported Azure OpenAI models. If you only deploy a subset, add model overrides before registering the provider.
{
"provider": "azure-openai",
"enabled": true,
"config": {
"apiKeySecretName": "azure-openai-api-key",
"resourceName": "your-resource-name"
}
}
Replace your-resource-name with your Azure OpenAI resource name and azure-openai-api-key with the secret name you created in Step 2.
Port uses the appropriate Azure OpenAI API version automatically. You don't need to specify the API version in your configuration.
Configure model overrides
With validate_connection=true, Port validates all supported Azure OpenAI models by default. If any model lacks a matching Azure deployment, validation fails and Port rejects the registration. Use the top-level overrides.models field to set "enabled": false for every model you have not deployed.
For example, if you only deploy gpt-5 under the Azure deployment name my-gpt-5-deployment, register the provider with the following configuration:
{
"provider": "azure-openai",
"enabled": true,
"config": {
"apiKeySecretName": "azure-openai-api-key",
"resourceName": "your-resource-name",
"modelDeployments": {
"gpt-5": "my-gpt-5-deployment"
}
},
"overrides": {
"models": {
"gpt-5": {
"enabled": true
},
"gpt-5.6-luna": {
"enabled": false
},
"gpt-5.6-terra": {
"enabled": false
}
}
}
}
Replace the resource, secret, and deployment names with your own values. Review the supported models and adjust the overrides to match your deployments.
Enabling only the models you want is not enough. Models you omit from overrides.models remain enabled by default, and modelDeployments does not limit which models Port validates. Explicitly disable every supported model without a matching deployment to avoid validation failure. See model overrides for more details.
Step 4: Validate the configuration
The validate_connection=true parameter tests your configuration by making a request to your provider. If validation succeeds, your provider configuration is saved. If it fails, check the error message for details.
For more troubleshooting steps, see the setup and configuration FAQ.
Common validation failures:
- Invalid API key: Verify your API key is correct and active in the Azure portal.
- Incorrect resource name: Ensure
config.resourceNamematches your Azure OpenAI resource name, without the URL scheme or domain suffix. - Missing or mismatched model deployment: Verify that every enabled model has an Azure deployment named after its Port model ID, or a
config.modelDeploymentsmapping to an existing deployment. - Undeployed models left enabled: Set
"enabled": falseinoverrides.modelsfor every supported model without a deployment. - Insufficient quota: Ensure your Azure OpenAI deployment has sufficient quota allocated.
After registration
Once your provider is configured:
- Set as default: Click your profile picture, select Settings, then open the AI tab, or use the Change default LLM provider and model API to set your provider as the organization's default.
- Use in API calls: Pass the provider name and a supported model name in individual general-purpose AI interactions or invoke a specific agent requests.
For more information on provider selection and validation flow, see Setup & Configuration.