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. Do one of the following:
    • In the workspace sidebar, click AI Gateway, then open the Providers tab and click Create.
    • In Catalog Explorer, go to the schema where you want to create the model provider service, then click Create > Service > Model provider service.
  2. Enter a name for the model provider service, and select the catalog and schema to create it in. If you start from Catalog Explorer, Catalog Explorer prefills the catalog and schema.
  3. Select the provider type, and enter the provider's connection details and credentials.
  4. Click Create. 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 requests to supported APIs. They do not apply to other APIs, 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