Connections

One connection per Snowflake account your workspace works with. It holds the account, the user Gondola authenticates as, and a credential:

Connections are scoped to the active workspace. Everyone in the workspace can see them; who can change them is covered below.

Each connection authenticates one of two ways. Pick per connection — bots inherit it from the connection they use.

Neither method is zero-setup on the Snowflake side: both need a service user, a role, and the right grants, and PATs additionally require a network policy on the service user before a token can be generated. The full runbook is in Prepare Snowflake below.

The openssl commands to generate a key pair and the ALTER USER statement to register the public key are below — you don't need to remember them. After you save a key-pair connection, Gondola shows a setup card with the exact ALTER USER statement for your username, plus the key's SHA256 fingerprint so you can confirm it matches what Snowflake has.

openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out rsa_key.p8
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

A standardized setup for the Snowflake side of a connection: a dedicated service account, a role with the grants Gondola needs, and the auth method. Everything below runs in a Snowflake worksheet — do it once per account before adding the connection in Gondola.

1. 1

   Create the service account

   As USERADMIN:

   Snowflake SQLCopy

   USE ROLE USERADMIN;
   CREATE USER svc_gondola
     TYPE = SERVICE
     COMMENT = 'Service account for Gondola (Cortex Agents)';

   TYPE = SERVICE users cannot log in with a password — programmatic access only.

2. 2

   Create the role and base grants

   As SECURITYADMIN:

   Snowflake SQLCopy

   USE ROLE SECURITYADMIN;
   CREATE ROLE gondola_agent_role;
   GRANT ROLE gondola_agent_role TO USER svc_gondola;
   GRANT USAGE ON DATABASE <database> TO ROLE gondola_agent_role;
   GRANT USAGE ON SCHEMA <database>.<schema> TO ROLE gondola_agent_role;
   GRANT USAGE ON WAREHOUSE <warehouse> TO ROLE gondola_agent_role;
   GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE gondola_agent_role;

3. 3

   Choose a privilege tier

   How much Gondola can do on this connection depends on the agent privileges you grant:

   Capability	Tier 1 — use agents only	Tier 2 — use + edit agents
   List agents; bots invoke them	Yes	Yes
   Create agents from Gondola	No	Yes
   Edit and delete agents	No	Yes

   Tier 1 — use and invoke existing agents only. Gondola can list agents and bots can call them:

   Snowflake SQLCopy

   GRANT USAGE ON ALL AGENTS IN SCHEMA <database>.<schema> TO ROLE gondola_agent_role;
   GRANT USAGE ON FUTURE AGENTS IN SCHEMA <database>.<schema> TO ROLE gondola_agent_role;

   Tier 2 — additionally create, edit, and delete agents from Gondola:

   Snowflake SQLCopy

   GRANT CREATE AGENT ON SCHEMA <database>.<schema> TO ROLE gondola_agent_role;

   Agents created through Gondola are owned by svc_gondola's role automatically, so updating and deleting them needs no further grants. The tier is per connection — you can register some connections tier-1 and others tier-2.

   Secondary: editing agents created outside Gondola

   There is no ALTER or DROP privilege on agents — update and delete require OWNERSHIP or MODIFY. To let Gondola edit agents created by other roles, add MODIFY:

   Snowflake SQLCopy

   GRANT MODIFY ON ALL AGENTS IN SCHEMA <database>.<schema> TO ROLE gondola_agent_role;
   GRANT MODIFY ON FUTURE AGENTS IN SCHEMA <database>.<schema> TO ROLE gondola_agent_role;

4. 4

   Pick an auth method

   Key pair

   Generate the pair with openssl:

   shellCopy

   openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -out rsa_key.p8
   openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

   Then register the public key on the service user:

   Snowflake SQLCopy

   -- Run as SECURITYADMIN:
   ALTER USER svc_gondola SET RSA_PUBLIC_KEY = '<public key body — no BEGIN/END lines>';

   You don't need to remember the statement — after you save a key-pair connection, Gondola shows it with your username filled in, plus the key's SHA256 fingerprint.

   Programmatic access token (PAT)

   SERVICE users must be subject to a network policy before a PAT can be generated or used, and ROLE_RESTRICTION is required:

   Snowflake SQLCopy

   -- As ACCOUNTADMIN: allow the networks Gondola connects from
   CREATE OR ALTER NETWORK POLICY gondola_pat_policy
     ALLOWED_IP_LIST = ('<your egress ip or cidr>');
   ALTER USER svc_gondola SET NETWORK_POLICY = gondola_pat_policy;
   
   -- Then create the token:
   ALTER USER svc_gondola ADD PROGRAMMATIC ACCESS TOKEN gondola_pat
     ROLE_RESTRICTION = 'GONDOLA_AGENT_ROLE'
     DAYS_TO_EXPIRY = 365;

   ROLE_RESTRICTION must match the role from step 2, uppercased: GONDOLA_AGENT_ROLE. The token secret is shown once — paste it into the Gondola connection form immediately. DAYS_TO_EXPIRY defaults to 15 days if omitted (range 1–365+).

   Lifecycle commands for the token:

   Snowflake SQLCopy

   SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER svc_gondola;
   ALTER USER svc_gondola ROTATE PROGRAMMATIC ACCESS TOKEN gondola_pat;
   ALTER USER svc_gondola REMOVE PROGRAMMATIC ACCESS TOKEN gondola_pat;

1. 1

   Open the form

   Connections → Add connection. Only owners and admins see the action.

2. 2

   Fill in the fields

   Name, account identifier, username, role, and an optional warehouse. Then pick the authentication method and paste the credential — the token, or the PKCS8 PEM private key.

3. 3

   Create connection

   The credential is encrypted on save. Gondola tests nothing until you ask it to, so a save can succeed before Snowflake is reachable — use Test to check.

4. 4

   Key pair only: finish in Snowflake

   The connection can't authenticate until Snowflake has the matching public key. The setup card that appears after saving walks it: run the shown ALTER USERstatement, check the fingerprint, then test. The same card stays available on the connection's page.

The optional Credential expires on date tracks expiry — Gondola fills it automatically for PATs when it can (see below), so you usually only set it yourself when auto-detect fails or to track key-pair rotation.

On the connection's page, click Test. The key-pair setup card has the same button as its last step.

• Success shows Connected with the Snowflake server version and latency.
• A credential problem shows Authentication failed — the credential may be expired or invalid. Hover the message for the raw server error.

Every test — pass or fail — is recorded in the workspace audit log.

When you save a PAT, Gondola reads its expiry from Snowflake on a best-effort basis — an explicit date you enter yourself wins, and if detection fails nothing is set. Rotating a PAT re-detects the date. Key pairs have no Snowflake-side expiry, so the date field is purely for tracking your own rotation schedule.

Where the date shows up:

• Connections list. The Credential expires column shows a neutral date badge normally, an amber Expires in N days (or Expires today) badge within 14 days, a red Expired badge past the date, and an em dash when no date is on file.
• Connection page. A warning banner appears 14 days out, turning into a danger banner once the date passes. Both point at the rotate card below the form.

Open the connection and scroll to Rotate credential. Paste the new token or private key and save — the old credential stops working as soon as you do. You can also set a new expiry date in the same card; leaving it blank keeps the current one (new PATs get their date re-detected either way).

To change auth method instead (say, PAT to key pair), switch the method in the edit form. That replaces the stored credential, so the form asks for the new one before you can save.

Key-pair rotation without downtime

Snowflake accepts two public keys at once. Register the new public key as RSA_PUBLIC_KEY_2, save the new private key in Gondola, then drop the old key from Snowflake. The old key keeps working until you switch.

Bots on the connection record a credential error: Snowflake credential is expired or invalid — update the connection's credentials. It appears as the bot's last error on its page and its activity page, and anyone who mentions the bot gets an error reply in the thread. The bot's status stays Active — a lapsed credential is recorded as an error message, not a shutdown.

Rotate the credential from the connection page and the bots recover on their own: Gondola re-reads the connection for every message, so the next mention uses the new credential. No deactivate/activate cycle needed.

• Owners and admins create, edit, rotate, delete, and test connections.
• Memberssee the list and each connection's details, read-only. The save, delete, and rotation controls are hidden, and the API refuses mutations from members either way.

Deleting a connection asks for confirmation and cannot be undone.