Skip to main content
Last updated on

Create and manage model provider services

Beta

this feature is in Beta. Account admins can manage access to this feature from the account console Previews page. See Manage 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 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. 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. Databricks encrypts it and does not return it on read.

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

Bash
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 Databricks service principal:

Bash
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.

SQL
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.

Bash
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​

On this page