How do employees sign in to an AI gateway?

Summary

• With Databricks Unity Gateway, employees sign in with the Databricks identity they already have. Requests carry an OAuth token or a personal access token for the workspace, and with single sign-on (SSO) that identity comes from your own identity provider.
• SSO supports SAML 2.0 or OpenID Connect. For most accounts unified login is on by default, so one SSO configuration covers the account and all its workspaces.
• Developers who connect coding agents can use the Unity Gateway CLI (ug), which authenticates on first run and keeps provider API keys off their machines.
• Signing in proves identity only. What an employee can call is set in Unity Catalog, for example by granting EXECUTE on a model service.
• Applications and automation authenticate as service principals with OAuth. When SSO is on, MFA is configured in your identity provider.

How do employees sign in to an AI gateway?

With Databricks Unity Gateway, employees sign in with the Databricks identity they already have. Requests carry a token for your workspace, either an OAuth token or a personal access token. When SSO is configured, workspace sign-in goes through your organization's identity provider, so employees use their normal corporate login. Signing in only proves who the caller is. Unity Catalog permissions decide which models that person can use. This page describes Unity Gateway, so check the documentation of any other gateway you run.

What is Unity Gateway?

Unity Gateway is the Databricks governance solution for enterprise AI. Built on Unity Catalog, it extends governance to the runtime interactions between models, agents, MCP servers, and tools. Teams use it to control which AI services people can use, route and manage AI traffic, and monitor usage from one control plane.

What are the ways to sign in to Unity Gateway?

Who signs in	Method	What to know
Employee in the workspace or Catalog Explorer	SSO through your identity provider	SSO supports SAML 2.0 or OpenID Connect
Employee using the CLI, an SDK, or a script	OAuth user-to-machine (databricks auth login)	Each access token is valid for one hour
Developer using a coding agent	The ug CLI	Authenticates on first run, with no provider API key on the machine
Quick test	Personal access token	The quickstart recommends OAuth for production use
Application or automation	Service principal with OAuth	OAuth is the preferred protocol for service principals outside the UI

After signing in with OAuth, send the token as a bearer token to the OpenAI-compatible endpoint:

databricks auth login --host https://<workspace-url>
export DATABRICKS_TOKEN=$(databricks auth token --host https://<workspace-url> | jq -r .access_token)

curl https://<workspace-url>/ai-gateway/mlflow/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -d '{"model": "system.ai.gpt-5-2", "input": [{"role": "user", "content": [{"type": "input_text", "text": "Hello!"}]}]}'

How does single sign-on work?

Databricks supports SSO with either SAML 2.0 or OpenID Connect (OIDC), and documents setup for identity providers such as Microsoft Entra ID and Okta. For most accounts, unified login is enabled by default, so a single SSO configuration is used across your account and all workspaces. When account-level SSO is enabled, all users, including admins, must sign in with SSO, and account admins can set up emergency access for selected users to prevent lockouts.

How are employee accounts created and removed?

Just-in-time (JIT) provisioning creates a user account automatically the first time someone signs in through your identity provider. To sync users and groups, Databricks recommends automatic identity management. SCIM provisioning is the alternative: it lets the identity provider create users, give them access, and remove access when they leave, and Databricks recommends the account-level connector.
When you remove a user from the account-level SCIM connector, that user is deactivated from the account and all of their workspaces. A deactivated user can't authenticate or access the Databricks UI or APIs, and tokens that user generated can't be used until the user is reactivated.

What can a signed-in employee call?

Authentication and authorization are separate steps. Unity Catalog controls who can use which models, and Unity Gateway enforces limits and records usage and cost. An admin opens the model service in Catalog Explorer and grants EXECUTE to users or groups on the Permissions tab.

How do coding agents sign in?

For external coding agents such as Claude Code or Codex, the tutorial recommends the Unity Gateway CLI, an open-source launcher that handles OAuth and writes each agent's configuration file. Install it with uv tool install git+https://github.com/databricks/unity-gateway, then run a command such as ug claude or ug codex. On first run, the CLI prompts for your workspace URL and authenticates; later runs go straight to the agent.

How do applications sign in?

Applications and unattended automation authenticate as a service principal, not as an employee, and Databricks prefers OAuth 2.0 for this. You create an OAuth secret for the service principal and supply DATABRICKS_HOST, DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET so supported tools can request access tokens. Databricks recommends personal access tokens only when OAuth isn't available for your use case.

How do you enforce MFA?

Configure it in your identity provider. When SSO is on, Databricks MFA is disabled by default and can't be changed, and Databricks recommends configuring MFA with your organization's identity provider. Without SSO, an account admin can set Databricks MFA to Recommended, Required, or Disabled.

FAQs

Do employees need a separate password for Unity Gateway?

No. Requests carry a Databricks token for your workspace, and with SSO configured, workspace sign-in goes through your identity provider.

What happens when an employee leaves?

With an account-level SCIM connector, removing the user deactivates them from the account and all workspaces, and their tokens stop working while they're deactivated.

Can applications use the gateway without an employee signing in?

Yes. Use a service principal with OAuth machine-to-machine authentication.