Developer Platform
Connect organization logs to Snowflake
Configure Snowpipe Streaming from tenant Admin or the scoped API, with Builder support access.
Who manages the connection?
Each tenant organization has its own Snowflake destination. Its active owner manages it in Admin → Snowflake. Builders intentionally have support authority: a Builder-managed live API credential can manage the connection when it has explicit Snowflake scopes and is bound to that organization's active owner. A delegated tenant-user credential may use the same routes. Ordinary organization members cannot administer the connection.
The server derives app, organization and user identity from the verified session or credential, then checks current ownership through secured stored procedures. An organization ID in a request body does not grant access. Builder support must select the correct organization principal before calling these routes.
What the Snowflake administrator needs
- A Snowflake account and permission to create a dedicated service user, role, database, schema and streaming pipes.
- The preferred
organization-accountidentifier, without a URL. This release supports public Snowflake endpoints. - A database, schema, dedicated role and dedicated service-user name. Use simple unquoted identifiers.
Save the destination to generate its key pair on the server. Copy the returned setup SQL into a Snowflake worksheet for an administrator to review and run. The script creates eight tables and pipes and grants USAGE on the database/schema, INSERT on the tables and OPERATE on the pipes. It creates a new SERVICE user and never replaces an existing user. No ingestion warehouse or staging bucket is required; your analytics queries use your own query role and warehouse. Snowflake charges apply separately.
Only the public key reaches the browser or API response. Private keys are encrypted on the server. Do not paste private keys, passwords or tokens into configuration fields. For key replacement, save with generateKey: true, run the returned keyRotationSql, and test again.
Public routes and scopes
All routes start with /v1/apps/{saasAppId}/organization/snowflake. The app path is checked against the credential; the organization comes from its verified principal.
| Method and suffix | Scope | Action |
|---|---|---|
| GET | modules.snowflake.read | Settings, public key, setup SQL, verification, checkpoints and recent history |
| PUT | modules.snowflake.write | Create/update settings or replace the key |
| POST /test | modules.snowflake.write | Check authentication and all eight pipes using separate test channels |
| PUT /enabled | modules.snowflake.write | Enable or pause export |
| POST /export | modules.snowflake.write | Export the next bounded batch |
Save accepts accountIdentifier, databaseName, schemaName, roleName, principalName, generateKey and, for updates, expectedRowVersion. Creating a destination requires key generation. Other mutations require the latest returned expectedRowVersion; enable/pause also requires an explicit boolean isEnabled. Read again after HTTP 409. Unknown body fields are rejected.
The generated BuildWithHQModuleClient exposes snowflakeGet, snowflakeSave, snowflakeTest, snowflakeSetEnabled and snowflakeExport. Pass save, test, enable and export payloads under body.
Test, enable and export
A saved or rotated connection stays paused until its connection test succeeds. Saving settings invalidates earlier verification. Test/export responses contain safe destination.lastResult codes; HTTP 200 alone does not prove a provider test succeeded. Require connected after testing or export_completed after exporting. HTTP errors use a safe explanation, stable code and correlation ID.
Each export handles up to 100 entries per dataset. Run another batch to continue. Stable channels and committed offsets recover an interrupted batch before advancing local checkpoints. A busy operation, stale revision, rejected rows or regressed remote offset stops progress safely. The history displays the latest 25 completed dataset runs. Pausing preserves history and data already in Snowflake.
Included datasets cover AI usage, login outcomes, page views, record changes, field access/changes, file access and automation job metadata. Passwords, session tokens, prompts, responses, record/file contents and raw diagnostic payloads are excluded. Export does not extend local diagnostic retention or create staged log files.
Current availability
Tenant Admin and the public API were exercised against the local routed test tenant. Snowpipe protocol and retry behavior were tested with documented local responses. Actual Snowflake ingestion remains unverified because no Snowflake account was available. Automatic scheduling, private connectivity, managed encryption-master-key rotation and destination moves after checkpoints require follow-up work. The current API reports schedulingAvailable: false.
If protected server key storage is unavailable, ask the operator to install the shared encryption key on the serving API instances. The operator must back it up separately from the Logs database; losing it requires replacing tenant connection keys.
References: account identifiers, key-pair authentication, Streaming REST tutorial, and access control.
Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.