Identity and permissions

What a user can reach through an agent comes down to four variables:

1. How the request authenticated — as a real user, or as a machine-to-machine OAuth client.
2. Whether they have access to that specific agent — every agent has its own access settings, independent of Alation role.
3. The user’s role and grants in Alation — the role drives catalog metadata visibility; per-object grants drive data-product access.
4. Which warehouse credential runs the query — the warehouse enforces that credential’s native permissions.

The second variable decides whether a user can reach an agent at all; the rest decide what they can do or see once they’re in. See Agents for how per-agent access works.

How you authenticate changes what you see

The authentication mode chosen at the entry point determines which identity and role drive the request. Agent Studio’s MCP server and REST APIs support two OAuth 2.0 modes.

Authentication mode	Also known as	Use it when	Effect
User-initiated OAuth (interactive)	3-legged OAuth, authorization-code flow	A person is present to authorize access	The request runs as the real user. Their role drives catalog visibility; their grants drive data-product access; their own warehouse credential is used by default. The standard, least-privilege path.
Machine-to-machine OAuth (service account)	2-legged OAuth, client-credentials flow	Automated integrations and scheduled flows, with no user present	The request runs with the role assigned to the OAuth application at creation. Assign that role deliberately — it sets the ceiling for everything the integration can reach.

To set up either mode, follow the client-creation guides: user-initiated or machine-to-machine.

Assign the M2M role deliberately

A machine-to-machine OAuth application acts with the role you assign it at creation, independent of any user. Scope that role to the minimum the integration needs. See Machine-to-machine authentication.

Does a user OAuth token inherit catalog permissions?

Yes. With user-initiated OAuth, the request carries the user’s own identity to every Alation service, so it inherits exactly the catalog visibility, data-product access, and per-agent permissions that user has in the Agent Studio web app. Two users with different roles, different agent grants, or different data-product grants get different results from the same agent.

With machine-to-machine OAuth, the request instead inherits the permissions of the role assigned to the OAuth application — not those of any individual user.

Roles and what they can reach

Agent Studio uses your existing Alation roles. The table below shows what each role can view and run by default, with no explicit grant — not what it can create, edit, or delete (see Permission matrices for that). See Agents below for how agent access can extend beyond this baseline, and Data-product visibility for how a grant changes the data-products column.

Global role	Agents	Data products	Catalog metadata
Server Admin	All (admin bypass)	All (admin bypass)	All
Catalog Admin	All (admin bypass)	Needs a grant	Broad
Source Admin	Needs a grant	Needs a grant	Source-scoped
Composer	Needs a grant	Needs a grant	Composer-scoped
Steward	Needs a grant	Needs a grant	Steward-scoped
Explorer	Needs a grant	Needs a grant	Cloud discovery
Viewer	Needs a grant	Needs a grant	Read-only

Catalog Admin is not a data-products admin

Only Server Admin bypasses data-product permissions. A Catalog Admin with no explicit grant on a restricted data product cannot see it — the same as any other role. This surprises teams who assume “catalog admin sees everything,” and it often leads to over-granting. Grant access to specific data products explicitly rather than relying on an admin bypass that does not exist for that role.

Permission matrices

By default you have full control over resources you create; restrictions apply to actions on other people’s resources. The same rules are enforced in the UI, the REST API, and over MCP — the acting role comes from how the caller authenticated.

For Agent Studio permissions, Alation roles group into four tiers:

Tier	Roles	Summary
Global	Server Admin	Full control over all resources, including other users’
Admin	Catalog Admin	Can see all Agent Studio resources (agents, tools, flows), edit others’ flows
Standard	Composer, Steward, Source Admin	Full control over own resources, can publish agents as tools
Restricted	Viewer, Explorer	Can view and use agents they have access to; cannot create, edit, delete, or clone agents or flows (can create and manage their own custom tools)

Agents

Every custom agent has its own access settings, managed from its Agent Access tab. A new agent starts with only its creator as Agent editor; anyone who is already an editor (including Server Admin) can then add other people, groups, or “everyone” at one of three agent roles:

• Agent viewer — see the agent’s configuration
• Agent user — also run it: chat, API, MCP tool calls
• Agent editor — also edit, delete, manage its access, and publish/unpublish or list it

What that agent role actually grants you depends on your Alation tier:

Agent role	Server Admin	Catalog Admin	Standard roles	Viewer / Explorer
Agent editor	Can view Can run Can edit	Can view Can run Can edit	Can view Can run Can edit	Can view Can run
Agent user	Can view Can run Can edit	Can view Can run	Can view Can run	Can view Can run
Agent viewer	Can view Can run Can edit	Can view Can run	Can view	Can view
Not added	Can view Can run Can edit	Can view Can run	—	—

In the Agent Access tab’s Agent privacy section, choose Public to grant “everyone” a role at once (the modern equivalent of publishing), or add specific users and groups while keeping the agent private overall. Default agents (SQL Agent, Deep Research, etc.) are always public to everyone and can’t be restricted.

Caution

Publishing an agent as an MCP tool and granting access to it are separate actions: publishing creates the tool entry, but whether anyone can actually see or call that tool still follows the agent’s own access settings. Listing an agent in the marketplace is likewise separate from access — listing doesn’t grant it, and unlisting doesn’t revoke it.

Access is also only checked at the outermost entry point: if you can run an agent or trigger a workflow, everything it composes internally — sub-agents, tools — runs too, without a separate check on each one.

Custom tools (SMTP / HTTP)

Custom tools have no visibility filtering — all custom tools are visible to all authenticated users.

Action	Server Admin	Catalog Admin	Standard roles	Viewer / Explorer
Create tool	Yes	Yes	Yes	Yes
Edit own tool	Yes	Yes	Yes	Yes
Edit others’ tool	Yes	No	No	No
Delete own tool	Yes	Yes	Yes	Yes
Delete others’ tool	Yes	No	No	No
See all tools	Yes	Yes	Yes	Yes

Flows

Two behaviors differ from agents: Catalog Admin can edit others’ flows, and Viewer/Explorer cannot trigger others’ flows.

Action	Server Admin	Catalog Admin	Standard roles	Viewer / Explorer
Create flow	Yes	Yes	Yes	Yes
Edit own flow	Yes	Yes	Yes	Yes
Edit others’ flow	Yes	Yes	No	No
Delete own flow	Yes	Yes	Yes	Yes
Delete others’ flow	Yes	No	No	No
See all flows	Yes	Yes	Yes	Yes
Trigger own flow	Yes	Yes	Yes	Yes
Trigger others’ flow	Yes	Yes	No	No

Ownership and role changes

Ownership is set by who created the resource and does not change when a user’s role changes. A Composer who creates an agent and is later downgraded to Viewer keeps their Agent editor role on that specific agent, but loses the ability to act on it above what Viewer allows — they can still see and run it, but not edit or delete it. For flows, which don’t have per-agent access settings, the same downgrade fully loses edit/delete on owned flows. Role changes take effect immediately on the next request.

Error responses

Status code	Meaning
404 Not Found	The resource is invisible to you (for example, another user’s private agent you have no grant on). The existence of the resource is not revealed.
403 Forbidden	You can see the resource but lack permission for the requested action.

Data-product visibility

A data product’s visibility is the combination of its privacy mode and the per-object grants on it.

Privacy mode	No grant	With a user or group grant	With an “everyone” grant
Public	Visible	Visible	Visible to all
Private (restricted)	Hidden (returns 404) even to non–Server Admin admins	Visible	n/a

Restricted products that you have no grant for return 404 Not Found rather than 403 Forbidden, so the existence of the product is not revealed. Use the access-request flow to obtain a grant.

Warehouse credentials

When an agent queries a warehouse, the warehouse authenticates a stored credential; the user’s Alation token never reaches it. Which principal that credential maps to depends on configuration.

Credential used	What the warehouse enforces
User’s own (SSO/OAuth, key pair, or basic)	The user’s own warehouse identity → that user’s native row, column, and object security
Shared service account	One shared principal for all users of the data product → per-user warehouse scoping and attribution are lost. Available only if your administrator has enabled it for the data product.

Resolution order: the user’s own active credential is preferred. A shared service account is used only when it is enabled for the data product and selected — it is an opt-in fallback, not the default.

Supported per-user warehouse mechanisms include Snowflake OAuth/SSO, Snowflake key pair, BigQuery per-user service-account key, basic username/password, and Redshift AssumeRoleWithSAML.

Snowflake RBAC, row access, and masking

On the default (user-own-credential) path, the warehouse sees the user’s own principal, so Snowflake RBAC, row-access policies, and masking policies all apply to that user exactly as they would for any direct connection. This is what lets you tell a security reviewer that warehouse-native controls are preserved per user — provided no shared service account is in use for the data product in question.

Worked examples

Viewer · user OAuth · own warehouse credential · public product. Sees all public agents and their tools, plus any agent they’ve been explicitly granted access to. Reads catalog metadata read-only. Sees the public data product. The warehouse query runs as the user’s own warehouse identity, so results respect their column and row grants. A clean least-privilege path.

Viewer · user OAuth · restricted product, no grant. Same agents and tools. The restricted product returns 404 — indistinguishable from not existing. The user must request a grant through the access-request flow.

Viewer · granted access to a private agent. Can’t see other users’ private agents, but can chat with and run the one agent they were explicitly granted access to — the same as if it were public — without being able to edit it or see who else has access.

Composer · user OAuth · shared service account · public product. Sees public agents and tools plus agents they’ve been granted access to, and can compose. The warehouse query runs as the shared service account, so the user sees whatever that account can see — not their own warehouse grants — and warehouse audit attributes the query to the service account. Alation still records that this user initiated the query.

Related pages

• Request lifecycle — how these checks run on a single request.