Back AI provider credentials with a Unity Catalog secret

Imagine you manage AI model services in Databricks and need to avoid static API keys in code. You can now associate a provider credential with a Unity Catalog-managed secret. The gateway reads the secret at query time, enabling key rotation without modifying the model service.

Use cases

• Store external provider API keys securely in Unity Catalog.
• Rotate keys without needing to update the AI model service.
• Avoid plaintext credentials in infrastructure definitions.

How to use

You can create the model provider service using the Python SDK to reference the secret.

from databricks.sdk.service import catalog as c

model_provider_service = w.ai_gateway.create_model_provider_service(
    parent="schemas/main.default",
    model_provider_service_id="my_provider",
    model_provider_service=c.ModelProviderService(
        comment="Routes to a custom OpenAI-compatible provider",
        config=c.ModelProviderServiceConfig(
            provider_type=(
                c.ModelProviderServiceConfigExternalModelProviderType
                .EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
            ),
            targets=[
                c.ModelProviderServiceConfigModelTargetConfig(
                    model="gpt-4o",
                    native_api_types=["openai/v1/chat/completions"],
                )
            ],
            custom=c.ModelProviderServiceConfigCustomProviderConfig(
                direct=c.ModelProviderServiceConfigCustomProviderDirectConfig(
                    base_url="https://api.example.com/v1",
                    api_key=c.ModelProviderServiceConfigProviderSecret(
                        plaintext="dummy-api-key"
                    ),
                )
            ),
        ),
    ),
)

What happens in this code:

1. Imports the catalog modules from the Databricks SDK.
2. Defines the identifier and parent schema where the service will be created.
3. Configures the custom provider type and points to the target model.
4. Sends the request to register the provider service in the catalog.

Limitations and requirements

• You must have CREATE SERVICE on the target schema, plus USE CATALOG and USE SCHEMA.
• To use Unity Catalog secrets, you must have READ SECRET permission on the specific secret.