Unity AI Gateway is built on Unity Catalog, enabling centralized governance for model APIs, external model providers, MCP servers, agents, skills, and tools across workspaces.

Use this guide to:

• Start new workloads directly on Unity AI Gateway.
• Migrate existing workloads.
• Review permissions and re-create the governance settings you need.

Use the migration notebook for step-by-step guidance and examples for moving to Unity AI Gateway.

Why migrate to Unity AI Gateway?

Unity AI Gateway provides the secure, governed path for AI usage. It brings Unity Catalog ACLs, cost controls, guardrails, and observability into one place across models, external providers, MCP servers, agents, and skills. 

Legacy endpoints remain workspace-bound and do not provide the same centralized governance model.

For more information, see the AI governance with Unity AI Gateway (AWS | Azure | GCP) documentation.

Choose the right path:

Start fresh with Unity AI Gateway

If you are not using AI Gateway, using it only casually, or setting up a new account or workspace, start directly with Unity AI Gateway.

1. Review access to Databricks-hosted model APIs

Unity AI Gateway adds new Databricks-hosted foundation model APIs (Model Services) in system.ai. Review these grants and restrict access where required. 

Users querying a model API need EXECUTE on the model API (Model Service) and USE CATALOG and USE SCHEMA on system.ai. See Choose how to grant access to Model APIs for guidance.

2. Enable Enforce Unity AI Gateway

Coming Soon! 

Turn on the Enforce Unity AI Gateway setting at the workspace level. This disables legacy Gateway experiences so all GenAI traffic can be centrally managed through Unity Catalog.

Legacy Gateway is disabled by default for new accounts and workspaces. Confirm that enforcement is enabled before onboarding users.

Migrate existing workloads

1. Identify active legacy usage

Identify which legacy endpoints are receiving traffic, their workspaces and callers, and which endpoints can already be retired. This is a two-step process:

1. Enable usage tracking on all legacy endpoints. This is idempotent - safe to re-run even if already enabled.
2. Identify which legacy endpoints are still receiving traffic, which workspaces use them, and who is calling them. Queries system.serving.endpoint_usage and system.serving.served_entities for recent traffic, callers, and last-request times. Only account administrators can query these system tables.

2. Configure model APIs and providers

Create or identify the required model API or external model provider, then configure the supported governance settings you need.

3. Update clients

After configuring the appropriate model API or external model provider, move each workload to Unity AI Gateway.

4. Validate migrated traffic

Use the example script below to validate that legacy traffic has stopped. It queries the recent usage table for each legacy endpoint and returns its request count and last-request time.

5. Optional: Set the legacy endpoint rate limit to 0

For a gradual migration, set an individual migrated legacy endpoint’s rate limit to 0 to prevent further traffic to it while leaving other legacy endpoints active. Repeat steps 2–5 for each remaining workload.

Use the example script below to set the rate limit to 0. It updates only the selected legacy endpoint, so you can phase out usage one endpoint at a time.

6. Enable Enforce Unity AI Gateway

After all required traffic has migrated successfully, enable Enforce Unity AI Gateway at the workspace level. This disables legacy Gateway endpoints for the workspace.

If the setting is not yet available in your workspace, contact Databricks Support or your account team after completing and validating the migration.

Reference

Review and grant permissions

Choose how to grant access to model APIs

By default, all account users have EXECUTE on system-provided model APIs. Every model API also requires USE CATALOG on system and USE SCHEMA on system.ai.

• Schema-level: Grant EXECUTE on system.ai for all current and future model APIs.
• Direct grants: Remove broad schema access and grant EXECUTE on individual model APIs for least privilege. Underlying model permissions do not grant model API access.
• ABAC GRANT policies (Beta): Grant EXECUTE to model APIs matching governed tags. Because ABAC only adds access, remove any broader grants.

Permission requirements

If you are enrolled in Foundation Model Unity Catalog Permissions preview

With FM Permissions Preview, access to a legacy endpoint is controlled by EXECUTE on the underlying system.ai MODEL. With Unity AI Gateway, access is controlled by EXECUTE on the Model API.

MODEL permissions do not automatically carry over to Model APIs. Customers should review Model API permissions and apply the same least-privilege approach they use today. MODEL permissions are still required for users who create Model APIs.

Provisioned Throughput: Today, customers in the FM Permissions preview need MODEL EXECUTE to create PT endpoints. (Coming soon) PT endpoint creation will also require CREATE_SERVICE.

Configure model APIs and providers

Re-create governance settings

Legacy settings remain on the legacy endpoint but do not carry over. Re-create the setting you need on the new Model API or External Model Provider:

• Access and controls: Permissions, rate limits, budgets, and Service Policies.
• Observability: Usage tracking and inference logging.
• Traffic: Routing and fallback.

Also update CI/CD or IaC workflows to use Unity AI Gateway APIs. 

If settings appear to be missing, nothing was deleted: the existing configuration remains on the legacy endpoint. Open the View legacy endpoints to review them, then re-create the settings you need on the new resource.

Configure each workload type

• Databricks-hosted models: Use the corresponding model API in system.ai, review its permissions, and re-create required settings before moving traffic. See Govern model APIs (AWS | Azure | GCP) documentation.
• External model providers: Create a Model Provider Service with the existing provider, credentials, exposed models, callers, and required Gateway configuration. Clients authenticate to Databricks, while the Model Provider Service manages credentials and governs permissions, rate limits, policies, and telemetry. Query it directly or create a model API for model-specific governance; the model API's settings then take precedence. See Query model APIs (AWS | Azure | GCP) documentation.
• Provisioned Throughput: Keep the existing PT endpoint in Model Serving. Create a model API that references it, re-create required settings, grant callers EXECUTE on the Model Service, and update clients to use the Unity AI Gateway URL and fully qualified model API name.

Update clients

API / SDK client migration

For Databricks-hosted models, update:

• base_url: /serving-endpoints → /ai-gateway/mlflow/v1
• Model: Endpoint name → Fully qualified model API name

client = OpenAI(
   api_key=token,
   base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

response = client.chat.completions.create(
   model="<fully-qualified-model-api>",
   messages=[...]
)

See Query model APIs (AWS | Azure | GCP) documentation.

For external models, query the Model Provider Service directly with its name in the request header, or create a dedicated model API for a specific model.

client = OpenAI(
   api_key=token,
   base_url="https://<workspace-url>/ai-gateway/openai/v1",
   default_headers={
       "Databricks-Model-Provider-Service":
           "<catalog>.<schema>.<model-provider-service>"
   },
)

response = client.chat.completions.create(
   model="<provider-model-name>",
   messages=[...]
)

See Query external model providers (AWS | Azure | GCP) documentation.

Authentication changes in Unity AI Gateway

OAuth and PAT authentication remain supported. The required PAT scope depends on the URL:

• Workspace /ai-gateway/ route: Use the recommended, least-privilege ai-gateway scope.
• Legacy regional *.ai-gateway.* host: Use the broader all-apis scope.

Calling the legacy regional URL with an ai-gateway-scoped PAT returns 403: required scopes: all-apis. Move the client to the workspace /ai-gateway/ URL, use an ai-gateway-scoped PAT, and re-test.

ai_query migration

Replace the legacy endpoint name with the supported Databricks-provided foundation-model endpoint:

-- Legacy
SELECT ai_query('<legacy-endpoint-name>', 'Summarize: ' || text)
FROM my_table;

-- Unity AI Gateway
SELECT ai_query('system.ai.<model-name>', 'Summarize: ' || text)
FROM my_table;

The caller needs EXECUTE on the corresponding Model Service in system.ai.

See ai_query (AWS | Azure | GCP) documentation.

Coding agent migration

Configure supported coding agents to route through Unity AI Gateway instead of connecting directly to the underlying model provider. Databricks provides ucode for this setup.

Install it:

uv tool install git+https://github.com/databricks/ucode

Launch a supported coding agent:

ucode codex
ucode gemini
ucode copilot
ucode opencode

This configures the coding agent to use Databricks authentication and Unity AI Gateway. See Integrate coding agents with model APIs (AWS | Azure | GCP) documentation.

If you use your own provider credentials, first create a Model Provider Service, then point the coding agent to it:

ucode claude --provider <catalog>.<schema>.<provider-service>

The coding agent authenticates to Databricks, while the Model Provider Service manages the external credentials. See Integrate coding agents with external model providers (AWS | Azure | GCP) documentation.