Access control and authentication¶

Access to Cortex Agents is governed by Snowflake’s role-based access control. This topic covers the database roles and privileges that let users create, manage, and call agents, along with the authentication methods the API supports.

API access roles¶

To call the Cortex Agents agent:run API, use a role that has been granted one of the following database roles:

SNOWFLAKE.CORTEX_USER: Grants access to all Covered AI Features, including Cortex Agents.
SNOWFLAKE.CORTEX_AGENT_USER: Grants access to Cortex Agents only.

By default, the CORTEX_USER database role is granted to the PUBLIC role, which is automatically granted to all users and roles. If you don’t want all users to have this access, use the ACCOUNTADMIN role to run the following command:

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE PUBLIC;

You can then grant access to specific roles instead. For more information, see Cortex LLM privileges.

Caution

The Cortex LLM privileges guidance also recommends revoking IMPORTED PRIVILEGES on the SNOWFLAKE database from the PUBLIC role:

REVOKE IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE FROM ROLE PUBLIC;

This optional revocation affects more than Cortex: it also removes PUBLIC’s access to other objects in the shared SNOWFLAKE database, such as ACCOUNT_USAGE views. Only run this command if you intend to restrict all of that access.

User requirements¶

Cortex Agents determines session permissions from the querying user’s default role, not the role active in their session. Every user who calls an agent must have:

A default role with the privileges described on this page.
A default warehouse, with USAGE on that warehouse granted to the default role.

If either is missing, agent calls fail even when the user’s current role has the required privileges.

At a minimum, the default role must be granted USAGE on the agent, on the database and schema that contain it, and on the user’s default warehouse:

GRANT USAGE ON DATABASE <database_name> TO ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;
GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> TO ROLE <role_name>;
GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE <role_name>;

After you set the required privileges, see Create and manage agents.

Limiting access to specific roles¶

To give only a subset of users access to Cortex Agents, use the SNOWFLAKE.CORTEX_AGENT_USER database role. Database roles can’t be granted directly to users (see GRANT DATABASE ROLE), so grant it to a custom role and assign that role to users.

The following example, run with the ACCOUNTADMIN role, creates the custom role cortex_agent_user_role, grants it the CORTEX_AGENT_USER database role, and assigns it to example_user:

USE ROLE ACCOUNTADMIN;
CREATE ROLE cortex_agent_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE cortex_agent_user_role;

GRANT ROLE cortex_agent_user_role TO USER example_user;

You can also grant the database role to an existing role:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE analyst_role;

Important

A role that also has the CORTEX_USER database role retains access to all Covered AI Features. To restrict such a role to Cortex Agents only, revoke CORTEX_USER from it using the ACCOUNTADMIN role:

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE analyst_role;

Agent privileges¶

The following privileges control who can create, manage, and use an agent:

Privilege	Object	Notes
CREATE AGENT	Schema	Required to create an agent.
USAGE	Agent	Required to query the agent to generate responses. The role also needs `USAGE` on the database and schema containing the agent.
USAGE	Warehouse	Required on the user’s default warehouse to run agent queries and tools.
MODIFY	Agent	Required to update the agent.
MONITOR	Agent	Required to view the agent’s threads, logs, and traces.
OWNERSHIP	Agent	Automatically granted to the role that creates the agent. Can be transferred to another role with GRANT OWNERSHIP.

For default role and warehouse requirements, see User requirements.

Additional privileges for tools¶

Because the agent runs with the querying user’s default role, that role also needs privileges on the objects used by the agent’s tools:

Privilege	Object	Notes
USAGE	Cortex Search service	Required to run the Cortex Search services configured on the agent. The role also needs `USAGE` on the database and schema containing the service.
USAGE	Database, schema, table	Required to access the objects referenced in the agent’s semantic view.
USAGE	Function or stored procedure	Required to run a custom tool. Stored procedures run with owner’s rights or caller’s rights as defined on the procedure. See Understanding caller’s rights and owner’s rights stored procedures.
USAGE	Referenced agent	Required to expand an `agent_toolset` reference. Silently skipped if missing. See Agent toolsets.

Authentication¶

Requests to the Cortex Agents API must include an authorization token. Snowflake REST APIs support authentication via programmatic access tokens (PATs), key pair authentication using JSON Web Tokens (JWTs), and OAuth. For details, see Authenticating Snowflake REST APIs with Snowflake.