Set Up Direct Access

Use this guide to choose and complete the Snowflake-side setup for Direct Access. It covers supported authentication methods for external clients and the admin actions needed for each one.

The RAI Native App is installed in your Snowflake account.
The user already has the required app access, or you are ready to grant it.

What direct access does

By default, RAI clients connect to the RAI Native App using service functions, which proxy requests through Snowflake. Direct Access allows RAI clients to communicate directly with the app’s secure [ingress endpoint], reducing per-call overhead by about 500ms compared to service functions, especially for users in close geographic proximity to your Snowflake account’s region.

PyRel users must enable Direct Access in their configuration to take advantage of lower latency connections for supported external clients. We recommend always enabling Direct Access. It is opt-in because it requires admin setup in Snowflake and may not be available for all client environments, but it is the preferred connection method.

How direct access connects to the app

Clients using Direct Access connect securely to the RAI Native App’s ingress endpoint over the public internet. An ingress endpoint is a secure web address where your RAI Native App instance accepts connections from clients. It’s the front door to your RAI Native App in the cloud.

You never need to hardcode this address. The Python client uses the configured Snowflake credentials to automatically discover the app’s ingress endpoint at runtime and stores it in a file on the user’s machine called /tmp/relationalai/endpoint.toml. If the address changes or goes down, the client will automatically attempt find the new one for you, helping ensure reliable connectivity even if the endpoint changes behind the scenes.

How security and permissions work with direct access

Direct Access uses the same RAI application roles and Snowflake role-based access control (RBAC) as Service Functions. All data access and permissions are still governed by Snowflake roles and grants.

To use direct access, users must have the rai_user application role for the RAI Native App. If you created the RAI_DEVELOPER Snowflake database role when setting up the RAI Native App, that role includes the necessary rai_user application role.

What the limitations of direct access are

Snowflake Notebooks and Snowflake Streamlit can’t use Direct Access because of network restrictions.
For very large data transfers, the Python client will automatically use Service Functions instead of Direct Access. This is because certain features needed by these formats are not supported by Direct Access and require Service Functions to work properly.

Choose a Direct Access authentication method

Use the table below to choose the authentication method developers should use for Direct Access and navigate to the corresponding setup instructions. You only need to complete the setup for the method or methods you plan to use.

What to use	When to use it
External browser via OAuth	Best when you want the lightest Snowflake-side setup for a person working from a browser-capable local environment. The tradeoff is that it depends on an interactive sign-in and is not suitable for headless automation.
Programmatic access token	Best when you need a simple credential for headless scripts or automation. The tradeoff is that you must issue, deliver, rotate, and protect the token as a secret.
Key-pair authentication	Best when you want non-interactive access without issuing PATs and can manage a Snowflake key pair for the user. The tradeoff is more setup and key-management overhead than the other two options.

Create an OAuth Security Integration for Direct Access

Requires the ACCOUNTADMIN or SECURITYADMIN Snowflake roles.

To enable OAuth authentication for Direct Access, an admin must first create a Snowflake OAuth security integration. This enables users to authenticate interactively and obtain access and refresh tokens.

Use the following SQL to create a public OAuth client for Direct Access:

Create the OAuth security integration. Execute the following SQL to create a public OAuth client for Direct Access:
```
-- Create a public OAuth client for Direct Access.
CREATE SECURITY INTEGRATION RAI_SECURITY_INTEGRATION
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'PUBLIC'
  OAUTH_ALLOW_NON_TLS_REDIRECT_URI = TRUE
  OAUTH_REDIRECT_URI = 'http://localhost:8001/snowflake/oauth-redirect'
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400;  -- Time in seconds
```
Use a confidential client if your organization requires it and adjust OAUTH_CLIENT_TYPE and secret handling accordingly. Users will need to provide the oauth_client_secret in their configuration if you choose this option. See the Snowflake docs for details on these options.

Any localhost URI works for the redirect. The Python client starts a local server to finish OAuth login, so the port in the URI must be open on the user’s machine. If users need a different port, update OAUTH_REDIRECT_URI and share the new value with them. You can also create multiple integrations with different redirect URIs if needed.
Share required values with users. After creating the security integration, run the following SQL to retrieve the client ID:
```
-- Inspect the created integration. Change the integration  name if you used
-- a different one in step 1.
DESC SECURITY INTEGRATION RAI_SECURITY_INTEGRATION;
```
Share the client ID, client secret (if using a confidential client), and the redirect URI with users so they can configure their Direct Access connection.

Issue a Programmatic Access Token for Direct Access

Requires the SECURITYADMIN or ACCOUNTADMIN Snowflake roles.

Use the following SQL to issue a Programmatic Access Token (PAT) for a user to authenticate headlessly.

Issue a PAT for the user.

-- Issue a PAT for a user with a role restriction and expiry.
ALTER USER <user_name>
  ADD PROGRAMMATIC ACCESS TOKEN DIRECT_ACCESS_TOKEN
  ROLE_RESTRICTION = 'RAI_DEVELOPER'  -- choose an appropriate role
  DAYS_TO_EXPIRY = 90; -- adjust as needed

Configure a network policy.

-- Create a permissive network policy (example; tighten for production).
CREATE NETWORK POLICY RAI_DIRECT_ACCESS_POLICY
  ALLOWED_IP_LIST = ('0.0.0.0/0');

-- Assign the policy to the user.
ALTER USER <user_name> SET NETWORK_POLICY = RAI_DIRECT_ACCESS_POLICY;

Deliver the token securely. Deliver the PAT out of band and instruct the user to store it securely. Instruct users to reference the token file in their Direct Access configuration.

Configure Key-Pair (JWT) Authentication for Direct Access

Requires the SECURITYADMIN or ACCOUNTADMIN Snowflake roles.

To enable key‑pair (JWT) authentication for, users first generate a private/public key pair locally, then an admin (or the user, per policy) registers the public key in Snowflake.

Generate a private/public key pair locally. Run openssl or another tool on their machine to create an RSA key pair:

# Generate a private key (omit -nocrypt to encrypt the key).
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

# Generate the corresponding public key.
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

Register the public key in Snowflake. An admin (or the user, per policy) must then run the following SQL to register the public key with the user’s Snowflake account:
```
-- Register the user's RSA public key.
ALTER USER <user_name>
  SET RSA_PUBLIC_KEY = '<public key contents>';  -- paste the contents of rsa_key.pub
```
Configure the user environment. After configuration the user must reference the private key (and password, if encrypted) in their Direct Access configuration.