# Snowflake Cortex Account And Request Context

Use this reference before constructing Snowflake Cortex REST API requests.

## Required Context

Confirm these values before live calls:

1. Snowflake account URL, for example `https://<account_identifier>.snowflakecomputing.com`.
2. Authentication method: programmatic access token, key-pair JWT, or OAuth.
3. Role intended for the request.
4. Warehouse, when an agent or tool can execute warehouse-backed work.
5. Database and schema containing the Cortex Agent object, when using object APIs.
6. Account region, when model availability or cross-region inference matters.

Use Snowflake account hostnames for Cortex APIs. Do not use Preset workspace
hostnames.

## REST Headers

Snowflake Cortex Agent REST requests use:

| Header | Value |
|---|---|
| `Authorization` | Required bearer token from the selected Snowflake auth method |
| `Content-Type` | Required `application/json` for JSON request bodies |
| `Accept` | Optional for `agent:run`; use `text/event-stream` for streaming, or `application/json` for non-streaming |
| `X-Snowflake-Authorization-Token-Type` | Optional. Use `OAUTH`, `KEYPAIR_JWT`, or `PROGRAMMATIC_ACCESS_TOKEN` when declaring the token type explicitly |

Never paste tokens, private keys, or signed JWTs into Markdown, logs, PR
comments, or handoff notes.

# Snowflake Cortex Agent Access And Region

Use this reference when planning Cortex Agent calls, object workflows, or model
availability checks.

## Access Checks

For Cortex Agent runs, verify the role has the required Snowflake Cortex Agent
access. Snowflake documents `SNOWFLAKE.CORTEX_USER` and
`SNOWFLAKE.CORTEX_AGENT_USER` as roles that can access Cortex Agents. Do not
treat `SNOWFLAKE.CORTEX_REST_API_USER` alone as sufficient for Cortex Agent
work; Snowflake's Cortex Agent access-control docs name `CORTEX_USER` and
`CORTEX_AGENT_USER` for Agent calls.

Agent object workflows also need object privileges:

- `CREATE AGENT` on the schema for creation.
- `USAGE` on the agent for runs.
- `MODIFY` on the agent for updates.
- `MONITOR` for threads, logs, and traces.
- Relevant database, schema, table, Cortex Search, semantic model, function, or
  warehouse privileges required by the agent's tools.

Use the user's default role when calling or updating Cortex Agents. Do not
silently switch to a broader role.

If the model is not locally available, check whether the account has an approved
`CORTEX_ENABLED_CROSS_REGION` setting before suggesting cross-region inference.

Official docs:

- <https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents>
- <https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-rest-api>
- <https://docs.snowflake.com/en/user-guide/snowflake-cortex/cross-region-inference>

# Snowflake Cortex Authentication And Context

Use this router before choosing the focused Cortex reference to retrieve.

- For account URL, auth method, role, warehouse, database/schema, request
  headers, and secret handling, use
  [account-auth-context.md](account-auth-context.md).
- For OAuth endpoint, scope, redirect URI, role, and token exchange checks, use
  [oauth-context.md](oauth-context.md).
- For Cortex Agent privileges, `SNOWFLAKE.CORTEX_USER`,
  `SNOWFLAKE.CORTEX_AGENT_USER`, object grants, default-role behavior, and
  `CORTEX_ENABLED_CROSS_REGION`, use
  [agent-access-and-region.md](agent-access-and-region.md).

Do not use Preset workspace hostnames for Snowflake Cortex APIs. Do not print
PATs, private keys, OAuth tokens, signed JWTs, or session tokens.

# Cortex Safety

Cortex Agent workflows can expose governed data, execute warehouse-backed tools,
and consume model or warehouse budget. Treat runs and mutations as
confirmation-gated.

## Confirmation Required

Before running a Cortex Agent or mutating an agent object, summarize:

1. Snowflake account URL and role.
2. Database, schema, and agent object name, or that this is an ad hoc run.
3. User query and any supplied instructions.
4. Tool names and tool resources, including Analyst, Search, SQL, generic
   function, MCP, or web-search resources.
5. Warehouse, timeout, and token budget where applicable.
6. Whether streaming or non-streaming output will be used.
7. Region or cross-region inference path when the selected model is not local.
8. Expected governed-data exposure and output destination.
9. Rollback path for create, update, replace, or delete operations.

Wait for explicit confirmation.

## Disclosure Rules

- Do not paste raw agent responses that contain governed data unless the user
  confirms the disclosure channel.
- Do not paste tool inputs, semantic model paths, warehouse details, or search
  filters if they reveal sensitive implementation details.
- Do not store streamed output in committed benchmark or PR artifacts.
- Handle unknown streaming event types without failing; Snowflake documents that
  clients should tolerate new event types.

## Live-Test Limits

Use a safe Snowflake test environment, a low-cost warehouse, and narrow budgets.
Do not run Cortex Agent APIs against production customer data without explicit
approval of the exact account, role, agent, query, and budget.

# Snowflake Cortex OAuth Context

Use this reference only for OAuth-backed Snowflake Cortex REST calls.

## OAuth Checks

1. Use Snowflake OAuth endpoints from the Snowflake account URL, not a Preset
   workspace hostname: `<snowflake_account_url>/oauth/authorize` and
   `<snowflake_account_url>/oauth/token-request`.
2. Confirm the security integration redirect URI matches the client redirect URI
   exactly, except that authorization-request query parameters are not included
   in the integration's `OAUTH_REDIRECT_URI`.
3. Use `scope=refresh_token` only when offline refresh is needed.
4. Use at most one `session:role:<ROLE_NAME>` scope. If omitted, the user's
   default role is used. Role names are case-sensitive; use uppercase for normal
   unquoted Snowflake roles. For escaped role names, use
   `session:role-encoded:<URL_ENCODED_ROLE_NAME>`.
5. Do not expect OAuth consent for blocked administrator roles. Snowflake blocks
   `ACCOUNTADMIN`, `SECURITYADMIN`, `GLOBALORGADMIN`, and `ORGADMIN` by default
   for custom OAuth clients.
6. Do not rely on secondary-role switching with Snowflake OAuth; choose a role
   that already has the needed Cortex Agent and object privileges.
7. For Cortex Agent REST calls and updates, prefer an OAuth token whose active
   role is the user's Snowflake default role. Verify role context before live
   calls.
8. Exchange authorization codes and refresh tokens at
   `<snowflake_account_url>/oauth/token-request` with
   `Content-Type: application/x-www-form-urlencoded` and HTTP Basic auth using
   `Base64(client_id:client_secret)`, unless using Snowflake's documented
   key-pair OAuth flow.
9. If the authorization request includes `code_challenge`, include the matching
   `code_verifier` in the authorization-code token request.
10. Verify the OAuth token can connect before using it for Cortex REST, for
    example with Snowflake CLI `snow connection test --authenticator=oauth`.