Create and manage external model providers (model provider services)

Register an external model provider as a model provider service, grant access to it, configure Unity AI Gateway features, and delete it.

Requirements

• CREATE SERVICE on the schema where you create the model provider service, plus USE CATALOG and USE SCHEMA on its catalog and schema.
• The credentials for the external provider you want to register (for example, an OpenAI API key or an AWS access key pair).
• To authenticate Azure OpenAI or Microsoft Foundry with a service credential instead of a key or secret, you need an existing service credential and ACCESS on it. See Authenticate Azure OpenAI or Microsoft Foundry with a service credential.

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.

You can create a model provider service in the Unity AI Gateway UI or in Catalog Explorer, or programmatically with the REST API, the Azure Databricks SDKs, the Azure Databricks CLI, or Terraform.

Catalog Explorer

1. Do one of the following:
   • In the workspace sidebar, click AI Gateway, then open the Providers tab and click Provider.
   • In Catalog Explorer, go to the schema where you want to create the model provider service, click Create > Service, then select Model provider service in the Create a service dialog.
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. Azure Databricks encrypts and stores the credentials. The UI does not display them after this point.

Developer Tools

Databricks CLI: Pass the parent schema and a leaf name, and supply the config with --json. Set provider_type and exactly one matching provider block; targets allowlists the reachable upstream models, and secrets are supplied inline as plaintext:

databricks ai-gateway create-model-provider-service schemas/main.default my_provider --json '{
  "comment": "Routes to a custom OpenAI-compatible provider",
  "config": {
    "provider_type": "EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM",
    "targets": [
      { "model": "gpt-4o", "native_api_types": ["openai/v1/chat/completions"] }
    ],
    "custom": {
      "direct": {
        "base_url": "https://api.example.com/v1",
        "api_key": { "plaintext": "dummy-api-key" }
      }
    }
  }
}'

Run databricks ai-gateway create-model-provider-service -h for all options. To install the CLI, see Install or update the Databricks CLI.

REST API: Use POST /api/2.1/unity-catalog/model-provider-services.

Terraform: Create and manage a model provider service using the Databricks Terraform provider and databricks_ai_gateway_model_provider_service.

Databricks SDKs: Create and manage model provider services with the Databricks SDK for Python, the Databricks SDK for Java, the Databricks SDK for Go, or the Databricks SDK for JavaScript.

For the full list of providers and their authentication methods, see Govern external model providers (model provider services).

Authenticate Azure OpenAI or Microsoft Foundry with a service credential

You can authenticate an Azure OpenAI or Microsoft Foundry provider with a service credential instead of storing an API key or a Microsoft Entra ID service principal client secret. A service credential holds an Azure identity that Unity Catalog governs, so no long-lived secret is copied into the model provider service: Azure Databricks obtains short-lived tokens from that identity to authenticate each request.

Create the model provider service as described in Create a model provider service. Select Azure OpenAI or Microsoft Foundry as the provider type and enter its connection details, including the endpoint base URL. Then set Auth method to Service credential and select the credential instead of entering an API key or client secret. A service credential replaces only the secret, so the endpoint base URL is still required.

Confirm the following requirements:

• The owner of the model provider service has ACCESS on the service credential. Because Azure Databricks re-checks the owner's access when serving requests, the owner must keep it for as long as the provider is in use. Revoking it stops queries for everyone, even callers who hold EXECUTE on the provider. To grant the owner access to the credential:

  GRANT ACCESS ON SERVICE CREDENTIAL <service-credential-name> TO `<model-provider-service-owner>`;
  

• The credential's purpose is service, not storage.

• The credential is available in the workspaces requests come from. Its workspace bindings still apply, so a request from a workspace the credential isn't bound to fails there, even though the model provider service itself is reachable from any workspace that shares the metastore.

• The service credential's Azure identity is authorized to call the Azure OpenAI or Microsoft Foundry deployments you plan to query. To create a service credential, see Create service credentials.

Callers who query the provider need the same grants as for any other provider. They don't need any privilege on the service credential, which is what keeps the credential itself out of their reach.

The model provider service tracks a credential by its internal identifier, so you can rename a credential without query failure.

If you delete a credential, queries fail and there is no warning that a model provider service references it. Confirm that there are no references to this credential before you delete it.

You can't switch an existing model provider service between service credential and API key or client secret authentication. Create a new model provider service instead.

Send a custom provider API key in a header

A custom provider sends its API key as a bearer token by default. When your endpoint expects the key in a specific header instead, use API key header authentication and name the header yourself. Azure Databricks then sends the key on each outbound request as <header name>: <header value>.

Create the model provider service as described in Create a model provider service. Select Custom as the provider type, then set Auth method to API key header and supply the Header name your endpoint expects (such as X-API-Key or Ocp-Apim-Subscription-Key) along with the Header value.

The two methods are mutually exclusive: a custom provider uses either a bearer token or a named header, not both. Header authentication takes exactly one header.

The header name must be a valid HTTP header name: letters, digits, and the characters !#$%&'*+-.^_`|~, up to 255 characters. Any other character is rejected, including spaces, colons, slashes, and line breaks.

Grant access

To let others query a model provider service, grant them EXECUTE on the model provider service and USE CATALOG and USE SCHEMA on its catalog and schema. If the model provider service logs to an inference table, grant SELECT on the table to let them read the logged requests and responses.

To grant access in Catalog Explorer:

1. In Catalog Explorer, open the model provider service.
2. On the Permissions tab, click Grant.
3. Select the users or groups to grant access to, select the EXECUTE privilege, and click Grant.

Make sure the same principals also have USE CATALOG and USE SCHEMA on the model provider service's catalog and schema. To let them read logged requests and responses, grant SELECT on the inference table from its Permissions tab.

For more about granting and discovering access, see Discover and govern access to external model providers (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:

• Inference logging. Log requests and responses to a Unity Catalog table. See Log requests and responses to inference tables.
• Rate limits. Cap queries per minute to manage capacity and cost. See Apply rate limits to model and MCP services.
• Service policies. Govern the content of each interaction, such as blocking unsafe content or redacting sensitive data, by attaching a service policy. See Service policies for AI securables and Create and attach a service policy.

Delete a model provider service

To delete a model provider service, you must have at least the MANAGE privilege on it. The owner has a superset of MANAGE.

To delete a model provider service, open it in Catalog Explorer and select Delete from the kebab menu. Deleting a model provider service removes its stored credentials.

Next steps

• Query external model providers (model provider services)
• Discover and govern access to external model providers (model provider services)
• Govern external model providers (model provider services)