OBO Authentication with Unity AI Gateway and databricks.agents.deploy()

[Froffri]

Hi everyone,

I'm trying to use the new Unity AI Gateway v2 (beta) endpoint from an agent deployed with the Mosaic AI Agent Framework and I'm running into what looks like a scope mismatch.

Library versions

databricks-agents==1.11.0
mlflow==3.12.0
python~3.12

Setup

I deploy my agent using:

databricks.agents.deploy(...)

and I configure OBO authentication through:

AuthPolicy(
    system_auth_policy=SystemAuthPolicy(...),
    user_auth_policy=UserAuthPolicy(
        api_scopes=[
            "sql",
            "unity-catalog",
            "vector-search",
            "model-serving",
        ]
    ),
)

The agent is able to successfully use OBO authentication for other Databricks services.

Goal

I want the agent to call a Unity AI Gateway endpoint (the new AI Gateway visible in the left navigation menu), using the end user's identity.

Problem

When the agent calls the AI Gateway endpoint, the request reaches the service but fails with an error similar to:

missing scope: ai-gateway

This suggests that the OBO token provided to the agent does not contain an ai-gateway scope.

However, when I try to add:

UserAuthPolicy(
    api_scopes=[
        "ai-gateway"
    ]
)

the deployment fails because ai-gateway is not recognized as a valid API scope.

Questions

1. Is OBO authentication currently supported for the new Unity AI Gateway endpoints when deploying with databricks.agents.deploy()?
2. If yes, what value should be added to UserAuthPolicy.api_scopes?
3. Is there currently a supported MLflow resource type or AuthPolicy configuration for AI Gateway endpoints?
4. If this is not yet supported, what is the recommended approach?

   Has anyone managed to successfully invoke a Unity AI Gateway endpoint from an OBO-authenticated Mosaic AI Agent?

   Thanks!

[Froffri]

I just want to add that I had the same exact issue when trying to use the VectorSearchClient class. However, instead of "ai-gateway", it requested "all-apis" as scope, which isn't in the allowed list when deploying the chatbot. 

[aliyasingh]

Based on what's currently documented, here's where things stand:

1. Is OBO supported for the new standalone Unity AI Gateway (the Beta one in the left nav, distinct from classic "AI Gateway on a serving endpoint")?

Not yet, as far as the public documentation shows. The UserAuthPolicy.api_scopes list that databricks-agents/MLflow's AuthPolicy recognizes is built from a fixed enum of REST API scope strings (things like serving.serving-endpoints, vectorsearch.vector-search-endpoints, dashboards.genie, sql, etc.), and ai-gateway isn't one of them which is exactly the validation error you're hitting. The standalone Unity AI Gateway (the one that logs to system.ai_gateway.usage and lives under the "AI Gateway" left-nav item, as opposed to the classic per-serving-endpoint AI Gateway) is itself still Beta, and OBO/per-user identity propagation into it from a Mosaic Agent Framework deployment doesn't appear to be wired up yet in databricks-agents==1.11.0 / mlflow==3.12.0.

2. What scope string should you use?

There isn't a published one yet. ai-gateway is not valid (as you found), and there's no ai-gateway.*-style scope documented alongside the others in the agent-authentication scope table.

3. Is there an MLflow resource type for it?

No, mlflow.models.resources currently only exposes DatabricksServingEndpoint, DatabricksVectorSearchIndex, DatabricksSQLWarehouse, DatabricksFunction, DatabricksGenieSpace, DatabricksTable, and DatabricksUCConnection. There's no DatabricksAIGateway/equivalent resource type for SystemAuthPolicy or UserAuthPolicy yet.

4. Workarounds people are actually using right now:

- If what you're really trying to reach is a Foundation Model API / model serving endpoint that happens to have AI Gateway features turned on (rate limits, guardrails, usage tracking, inference tables), that's still just a serving endpoint under the hood query it with the serving.serving-endpoints scope and DatabricksServingEndpoint resource, same as any other Model Serving OBO call. The "AI Gateway" branding on that endpoint doesn't change the auth path.
- If you specifically need the standalone Unity AI Gateway product (the one governing MCP servers, external models, coding-agent routing, etc.), OBO from a deployed Agent Framework model isn't supported yet — the documented pattern (Databricks Apps with user_api_scopes in databricks.yml/UI, e.g. serving.serving-endpoints, dashboards.genie) is for Databricks Apps, not agents.deploy(). So today the practical option is to either (a) call it with system/service-principal auth instead of OBO, accepting that you lose per-user attribution, or (b) move that piece of the workflow into a Databricks App, which does support broader, more granular OAuth scopes including newer ones as they roll out.
- Since this is a Beta feature, scope support is actively changing worth filing this directly with your Databricks account team / support, since ai-gateway OBO scopes for Agent Framework deployments sound like exactly the kind of gap they'd want a paying-customer signal on.

I'd treat this as "not supported yet" rather than "you're missing a flag" nothing in the current docs shows a valid scope value for it. If you want, I can help you check via databricks api get or the SDK whether your workspace's scope enum has anything AI-Gateway-related that isn't yet in public docs.

[iyashk-DB · Accepted solution]

This isn't a config problem on your end, it's a support gap. On-behalf-of auth for the standalone Unity AI Gateway beta endpoint isn't supported yet when you're deploying through databricks.agents.deploy().

Specifically, "ai-gateway" isn't a valid value in UserAuthPolicy.api_scopes right now, which is exactly why deployment fails as soon as you add it. There's also no MLflow resource type for standalone AI Gateway yet, so there's no SystemAuthPolicy or UserAuthPolicy resource path you can point at it either. It's just not wired up on the agent auth side at the moment.

A couple things worth checking before you go further down this path:

If what you actually want is a model serving or Foundation Model endpoint that happens to have AI Gateway features turned on, you don't need any of this. Call it like a normal serving endpoint using the serving endpoint scope, the AI Gateway branding on top doesn't change how auth works there.

If you specifically need the standalone Unity AI Gateway product (the one in the left nav), your options today are limited. You can fall back to service-principal or system auth instead of OBO, but you'll lose per-user attribution on those calls. The other option is to move that piece of the workflow into a Databricks App instead, since Apps support a broader set of OAuth scopes and that's the documented pattern for this kind of thing right now, agents.deploy() just isn't.

So don't add ai-gateway to UserAuthPolicy.api_scopes, it won't work. If a serving endpoint gets you what you need, use that. Otherwise, service-principal auth or a Databricks App are your workarounds until OBO support lands for standalone AI Gateway.