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.

REVOKE IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE FROM ROLE PUBLIC;

User requirements¶

Cortex Agents determines permissions from the Snowflake context of the request. For REST API calls, the authentication method, such as a programmatic access token (PAT), OAuth, key pair authentication, or a session token, identifies the caller. The role used to authorize the request comes from the X-Snowflake-Role header, or from the user’s default role if the header is omitted. If the request or session context activates secondary roles, those roles also govern privilege checks and data protection policy evaluation.

For calls made from Snowsight or CoWork, the role selected in the UI is used to authorize the request. If no role is selected, Snowflake uses the user’s default role.

Every user who calls an agent must have:

• An active role with the privileges described on this page.
• Access to any secondary roles that must be active for the run.
• USAGE on the warehouses configured for the agent’s tools.

At a minimum, the active role must be granted USAGE on the agent and on the database and schema that contain it. Grant USAGE on each tool warehouse to a role that is active in the caller’s session:

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;

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE analyst_role;

Agent privileges¶

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

For role and warehouse requirements, see User requirements.

Additional privileges for tools¶

Because the agent uses the caller’s session roles, those roles also need privileges on the objects used by the agent’s tools:

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.