Create and manage model provider services

Important

this feature is in Beta. Account admins can manage access to this feature from the account console Previews page. See Manage Azure Databricks previews.

This page describes how to create a model provider service, grant access to it, configure Unity AI Gateway features, and delete it.

Requirements

  • Unity AI Gateway preview enabled for your account. See Manage Azure Databricks previews.
  • CREATE SERVICE on the schema where you create the model provider service, plus USE CATALOG and USE SCHEMA on its catalog and schema.
  • CREATE CONNECTION on the same schema. Creating a model provider service with inline credentials stores them in a Unity Catalog connection, which requires this privilege.
  • The credentials for the external provider you want to register (for example, an OpenAI API key or an AWS access key pair).

Create a model provider service

Model provider services and model services share a single name namespace within a Unity Catalog schema. You can't use a name for a model provider service if a model service in the schema already uses it, and vice versa.

Use the UI

  1. In Catalog Explorer, go to the catalog and schema where you want to create the model provider service.
  2. Create a model provider service, select the provider type, and enter the provider's connection details and credentials.
  3. Save the model provider service. Azure Databricks encrypts and stores the credentials. The UI does not display them after this point.

Use the REST API

Create a model provider service with a POST to the model provider services endpoint. The parent query parameter is the schema resource name, and model_provider_service_id is the leaf name. Supply the credential inline as plaintext. Azure Databricks encrypts it and does not return it on read.

The following example registers an OpenAI provider with an inline API key.

curl https://<workspace-url>/api/2.1/unity-catalog/model-provider-services \
  -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -G \
  --data-urlencode "parent=schemas/main.default" \
  --data-urlencode "model_provider_service_id=openai_prod" \
  --data '{
    "config": {
      "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_OPENAI",
      "openai": { "direct": { "api_key": { "plaintext": "sk-..." } } },
      "targets": [
        {
          "model": "gpt-5.5",
          "native_api_types": ["openai/v1/chat/completions", "openai/v1/responses"]
        }
      ]
    },
    "comment": "Production OpenAI provider"
  }'

targets lists the specific models the model provider service can route to, each with the provider-native API types it supports. To instead allow any model the provider offers, set allow_all_targets to true and omit targets.

Note

targets and allow_all_targets restrict only managed-path requests. They do not apply to unmanaged passthrough requests, which are forwarded to the provider unchanged when forward_unmanaged_paths is enabled.

Other providers set a different block inside config and use the matching provider_type. For example, an Azure OpenAI provider that authenticates with a Microsoft Entra ID service principal:

curl https://<workspace-url>/api/2.1/unity-catalog/model-provider-services \
  -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -G \
  --data-urlencode "parent=schemas/main.default" \
  --data-urlencode "model_provider_service_id=azure_openai_prod" \
  --data '{
    "config": {
      "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_AZURE_OPENAI",
      "azure_openai": {
        "direct": {
          "base_url": "https://myresource.openai.azure.com",
          "tenant_id": "<tenant-id>",
          "client_id": "<client-id>",
          "client_secret": { "plaintext": "<client-secret>" }
        }
      },
      "targets": [
        {
          "model": "gpt-5.5",
          "native_api_types": ["openai/v1/chat/completions", "openai/v1/responses"]
        }
      ]
    },
    "comment": "Azure OpenAI provider (Entra ID)"
  }'

For the full list of providers and their authentication methods, see Model provider services in Unity Catalog.

Grant access

Grant EXECUTE to let a user or group query the model provider service. The principal also needs USE CATALOG and USE SCHEMA on the catalog and schema.

GRANT USE CATALOG ON CATALOG main TO ai_team;
GRANT USE SCHEMA ON SCHEMA main.default TO ai_team;
GRANT EXECUTE ON MODEL PROVIDER SERVICE main.default.openai_prod TO ai_team;

For more on governing access, see Discover and govern access to model provider services.

Configure features

Because a model provider service routes through Unity AI Gateway, apply the same governance and observability features you use for other Unity AI Gateway traffic:

Delete a model provider service

Delete a model provider service from the UI, or with a DELETE request to its resource name. Deleting a model provider service removes its stored credentials.

curl https://<workspace-url>/api/2.1/unity-catalog/model-provider-services/main.default.openai_prod \
  -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"

Next steps

  • Last updated on