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 account 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:54321/snowflake/oauth-redirect'
  OAUTH_ENFORCE_PKCE = TRUE
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400  -- Time in seconds (1 day)
  ALLOWED_ROLES_LIST = ('RAI_ADMIN', 'RAI_DEVELOPER');
```
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.
- The redirect URI must be a plain-HTTP localhost address. The RAI Python client completes sign-in on a local loopback callback that has no TLS, so OAUTH_ALLOW_NON_TLS_REDIRECT_URI = TRUE applies only to that address. Do not reuse it for a public HTTPS redirect.
- OAUTH_ENFORCE_PKCE = TRUE hardens the flow; the RAI client always sends a PKCE challenge.
- OAUTH_REFRESH_TOKEN_VALIDITY = 86400 means users complete interactive sign-in again once a day.
- ALLOWED_ROLES_LIST limits which roles can sign in. Add any custom account roles you granted RAI application roles. Snowflake still blocks privileged roles such as ACCOUNTADMIN.
- PyRel starts a temporary callback server on the URI’s port during sign-in, then closes it. Users do not run a server themselves. The port must be available on each user’s machine. To use a different port, update OAUTH_REDIRECT_URI and share the new value. You can also create multiple integrations with different redirect URIs.
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.

Run this SQL to create the token and set how long it lasts:
```
-- 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 = 15; -- Snowflake's default; adjust to your rotation policy
```
ROLE_RESTRICTION ties the token to a single Snowflake role, and the token can only ever act as that one role. So choose a role that’s already granted to the user and has every privilege they need. Use RAI_DEVELOPER for development, or a narrower role of your own for production. Snowflake ignores the user’s other roles when the token is used, so the token can’t fall back on them.

The token secret appears only once, in the output of this command. Copy it immediately and deliver it over a secure channel. You cannot retrieve it later.
Verify the token.

Confirm the token was created with the settings you intended before you deliver it:
```
SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER <user_name>;
```
Find DIRECT_ACCESS_TOKEN in the results and check its details, such as the role_restriction, expires_at, and status columns.
Configure a network policy.

A PAT requires a network policy on the user. Inspect any existing policy first, because a user-level policy overrides the account-level policy:
```
SHOW PARAMETERS LIKE 'NETWORK_POLICY' IN ACCOUNT;
```
If you have an existing policy that already covers this user, assign it instead of creating a new one. Otherwise, create and assign a policy:
```
-- Bootstrap only. ALLOWED_IP_LIST = ('0.0.0.0/0') allows every address.
CREATE NETWORK POLICY IF NOT EXISTS 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;
```
ALLOWED_IP_LIST = ('0.0.0.0/0') is for initial testing only, not production. It allows connections from any address, so a leaked token could be used from anywhere. Before production, replace the allow-all rule with your organization’s approved network rules and policies, and confirm you are not weakening an existing account restriction for this user.
Deliver the token securely. Deliver the PAT out of band, for example through a secrets manager, 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 encrypted RSA key pair:

# Generate an encrypted private key. OpenSSL prompts for a passphrase.
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8

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

# Restrict the private key file to your user only.
chmod 600 rsa_key.p8

The developer keeps the encrypted private key and its passphrase and never shares them. They send the admin only the public key (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, excluding the -----BEGIN/-----END lines
```
Verify the registered key’s fingerprint with DESC USER <user_name> and compare it to the developer’s local key.
Configure the user environment. After configuration the user must reference the private key (and passphrase) in their Direct Access configuration with private_key_passphrase.

Rotate keys without downtime

Snowflake supports two public keys per user. To rotate, register the new public key in RSA_PUBLIC_KEY_2, switch the developer to the new private key, then remove the old key:

ALTER USER <user_name> SET RSA_PUBLIC_KEY_2 = '<new public key contents>';
-- After the developer switches to the new private key:
ALTER USER <user_name> UNSET RSA_PUBLIC_KEY;