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, you can revoke the grant from the PUBLIC role and grant access to specific roles instead. For more information, see Cortex LLM privileges.

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.
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.

Note

Cortex Agents determines session permissions from the querying user’s default role, so agents are called and updated using that role. Each user who interacts with an agent must have a default role and a default warehouse set, and their default role must be granted USAGE on the database, schema, and agent:

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>;

For more information, see Create and manage agents.

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.

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.