Snowflake Gen AI Governance · Topic 5 of 15
REST API Authentication and Granting or Revoking Cortex Access
Authenticate to Cortex REST APIs with PATs, key pair JWT or OAuth, set the role with X-Snowflake-Role, and grant or revoke Cortex RBAC cleanly.
- 5 min
- REST authentication methods: programmatic access token, key pair JWT, OAuth.
- Role comes from
X-Snowflake-Role, otherwise the default role. - Database roles go to roles, never directly to users.
What it is
Cortex features are reachable two ways. In SQL, your session already carries an identity. Through the REST APIs (for example the Cortex Agents agent:run endpoint, the Cortex Analyst API, Cortex Search queries and the Cortex REST inference APIs), your application must send a token that proves who is calling.
Whichever way the call arrives, Snowflake checks the same RBAC: the active role needs the Cortex database role and the object privileges. Authentication answers "who are you"; grants answer "what may this role do".
How it works
Authentication methods
Every request sends an Authorization header with a token and Content-Type: application/json. The accepted token methods for Cortex Agents are:
| Method | Typical use |
|---|---|
| Programmatic access token (PAT) | Simple service scripts and quick tests; the token is tied to a user |
| Key pair authentication with a JSON Web Token (JWT) | Server to server automation with no interactive login |
| OAuth | Applications acting for users through an identity provider |
The Cortex Analyst documentation shows a session token in its example, but the same rule holds: an authorization token must be present.
Which role is used
For REST calls the X-Snowflake-Role header sets the primary role. If you omit it, the user's default role is used. In Snowsight or the Snowflake Intelligence app the role selected in the UI is used, or the default role. If the session activates secondary roles, those also take part in privilege checks and data protection policy evaluation.
A REST call that fails with a permission error often means the default role lacks the grants. Send X-Snowflake-Role with the role that has them, or fix the default role.
Tools use warehouses from the agent spec
For server-side tools in Cortex Agents, the warehouse comes from the agent specification, and the caller needs USAGE on it. Name the warehouse explicitly for Analyst and custom tools.
Granting and revoking Cortex access
Cortex database roles live in the SNOWFLAKE database and cannot be granted directly to users. Grant them to a custom role, then grant that role to users.
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;
Restricting access that PUBLIC already has
SNOWFLAKE.CORTEX_USER and the USE AI FUNCTIONS account privilege are granted to PUBLIC by default. Granting a narrower role changes nothing while PUBLIC still holds the broad one. Revoke from PUBLIC first.
REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE PUBLIC;
REVOKE USE AI FUNCTIONS ON ACCOUNT FROM ROLE PUBLIC;
REVOKE IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE FROM ROLE PUBLIC;
The last statement is described as optional. It also removes PUBLIC's access to other objects in the SNOWFLAKE database, such as the ACCOUNT_USAGE views. Also revoke CORTEX_USER from any other role that holds it, because a role that keeps CORTEX_USER keeps access to all covered AI features.
Per-function privileges
You can grant one function instead of all of them. Privilege checks use an OR relationship, so a blanket USE AI FUNCTIONS grant overrides any per-function revoke. Per-function grants still need CORTEX_USER or AI_FUNCTIONS_USER.
GRANT USE AI FUNCTION AI_COMPLETE ON ACCOUNT TO ROLE ai_complete_user_role;
REVOKE USE AI FUNCTION AI_COMPLETE ON ACCOUNT FROM ROLE ai_analyst_role;
SHOW GRANTS TO ROLE ai_analyst_role;
Checking what a role really has
After changing grants, verify rather than assume. SHOW GRANTS TO ROLE <role> lists what a role holds, including database roles. SHOW GRANTS OF DATABASE ROLE SNOWFLAKE.CORTEX_USER shows who holds the database role, which is the quick way to confirm PUBLIC no longer has it. Remember that a user inherits privileges from every role in the hierarchy and, in a session, from active secondary roles, so test with a fresh session and USE SECONDARY ROLES NONE.
Stored procedures and restricted caller's rights
AI functions can run inside stored procedures and services. With restricted caller's rights the privilege must be granted in a particular way. For a Snowpark Container Services service, grant USE AI FUNCTIONS to the session role and CALLER USE AI FUNCTIONS ON ACCOUNT to the service owner role. For procedures created with EXECUTE AS RESTRICTED CALLER, the creating role needs inherited caller usage on the schemas and functions in the SNOWFLAKE database. This is an edge case, but it explains why a function works in a worksheet and fails inside a procedure.
Common mistakes
Granting a database role straight to a user. It must go to a role.
Granting without revoking from PUBLIC. The restriction has no effect.
Forgetting the role header on REST calls. The default role is used and may lack grants.
Revoking one function while USE AI FUNCTIONS stays granted. The blanket privilege still allows it.
Revoking IMPORTED PRIVILEGES without thinking. It also removes access to ACCOUNT_USAGE views for PUBLIC.
What to remember for the exam
- REST authentication methods: programmatic access token, key pair JWT, OAuth.
- Role comes from
X-Snowflake-Role, otherwise the default role. - Database roles go to roles, never directly to users.
- Revoke from PUBLIC before granting to a team.
- USE AI FUNCTIONS (blanket) overrides per-function revokes.
Check yourself
Name three ways to authenticate to the Cortex Agents REST API.
A programmatic access token, key pair authentication with a JWT, or OAuth.
A REST call has no role header. Which role applies?
The user's default role.
Why does granting CORTEX_AGENT_USER not limit a user who also holds CORTEX_USER?
CORTEX_USER already covers all covered AI features, so it must be revoked, including from PUBLIC.
Topic 5 of 15 in Snowflake Gen AI Governance
Test yourself on Snowflake Gen AI Governance
The full Snowflake GES-C02 question bank has 585 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by Snowflake. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.