Skip to main content

Public Keys

View and manage encryption keys that protect your datasource credentials.

Overview​

Public Keys shows all encryption keys used to secure sensitive datasource credentials in your organization. Supaflow uses public-key encryption to ensure that only authorized agents can access your database credentials and connection details.

Two types of encryption keys:

  • System Key - Shared encryption key managed by Supaflow (default for all new organizations)
  • Private Keys - Tenant-specific RSA keys generated by your private agents (enhanced security and data isolation)

When you deploy a private agent, it automatically registers its own public key for enhanced security.

To access: Navigate to Settings → Public Keys in the sidebar.

Why Public Keys Matter​

Public keys are used to encrypt sensitive data like datasource credentials. Each key has a unique fingerprint and version that identifies it.

How it works:

  1. When you create a datasource, Supaflow encrypts the credentials using a public key
  2. The matching private key is stored securely with your agent (in Snowflake Secrets for SPCS agents)
  3. Only agents with the private key can decrypt and use those credentials
  4. Your credentials are never stored or accessible in plain text

Security benefits of private keys:

  • Tenant-specific keys (not shared with other Supaflow customers)
  • Private key never leaves your agent environment
  • Enhanced data isolation and security
  • Meets compliance requirements (SOC 2, HIPAA, etc.)

Understanding Your Keys​

Key Information Displayed​

For each encryption key, you'll see:

  • Key Identifier - The agent name or "system_key" for the shared system key
  • Fingerprint - Unique SHA-256 hash that identifies this specific key
  • Version - Key version number (higher = newer)
  • State - Whether the key is active, inactive, or pending approval
  • Datasources - How many datasources use this key
  • Created - When the key was first registered
  • Last Updated - When the key was last modified

Key States​

StateWhat It Means
ActiveKey is active and can encrypt/decrypt credentials
InactiveKey has been deactivated and is no longer in use
Pending ApprovalKey is awaiting admin approval (agent needs to be approved)
HistoricalOld key version that's been replaced by a newer key

Summary Metrics​

When you have private keys deployed, you'll see three key metrics:

  • Total Keys - Count of all your private keys
  • Active Keys - How many keys are currently active
  • Latest Active Version - The highest version number among your active keys

Validating Your Encryption Setup​

After deploying a private agent, verify that your encryption is properly configured:

  1. Go to Settings → Public Keys
  2. Check that you see at least one key with "Active" state
  3. Verify the key has a green checkmark indicating it's ready to use
  4. Note the fingerprint and version for reference

This confirms your agent registered its public key successfully and is ready to handle encrypted datasources.

Rotating Encryption Keys​

When to Rotate Keys​

System → Private migration:

  • When you first deploy a private agent
  • To migrate existing datasources from system key to private key
  • For enhanced security and data isolation

Private → Private rotation:

  • After a security incident
  • As part of regular security maintenance (annually recommended)
  • When retiring an old agent

How to Rotate Keys​

Prerequisites:

  • Active private key exists
  • Agent with that key is connected and running
  • Datasources exist that need migration

Steps:

  1. Ensure your private agent is running (check Agents page)
  2. Go to Settings → Public Keys
  3. Click Rotate Keys button (top right)
  4. Supaflow creates a re-encryption job automatically
  5. Monitor the job on the Activities page (takes ~1-2 minutes per 100 datasources)
  6. Verify datasources were re-encrypted successfully

What happens during rotation:

  • Each datasource's credentials are decrypted using the old key
  • Credentials are immediately re-encrypted using the new key
  • Datasource encryption fingerprint is updated
  • Process runs asynchronously without disrupting your pipelines

When Rotate Keys is Disabled​

If the Rotate Keys button is grayed out, hover over it to see why:

  • "No active private agent key found" - Deploy a private agent first
  • "Private key is inactive" - Go to Agents page and approve your agent
  • "No active agent with this key is connected" - Check that your agent is running
  • "No datasources on system key to rotate" - All datasources already migrated (you're done!)

Datasource Encryption Status​

For each encryption key, you can see how many datasources use it:

  • Total datasources - All datasources encrypted with this key
  • Active datasources - Datasources currently in use
  • Inactive datasources - Datasources that have been deactivated or deleted

If a datasource shows a mixed encryption warning, it means some credentials are on one key and others are on a different key. This usually indicates a failed re-encryption and should be addressed immediately.

Empty State: System-Managed Keys Only​

If you haven't deployed a private agent yet, you'll see a message indicating you're using system-managed keys.

To upgrade to private keys:

  1. Click Go to Agents button
  2. Follow the deployment workflow to set up a Snowflake SPCS agent
  3. Approve the agent once it registers
  4. Return to Public Keys page and click Rotate Keys to migrate your datasources

Troubleshooting​

Can't Rotate Keys - Button is Disabled​

What it means: One or more prerequisites aren't met for key rotation.

How to resolve:

If tooltip says "No active private agent key found":

  1. Go to Settings → Agents
  2. Deploy a Snowflake SPCS agent
  3. Wait for the agent to register
  4. Approve the agent to activate its key
  5. Return to Public Keys and try again

If tooltip says "Private key is inactive - agent needs to be approved":

  1. Go to Settings → Agents
  2. Find the agent with "Registered" or "Pending Approval" status
  3. Click Approve button
  4. Wait for the agent to become active
  5. Return to Public Keys and try again

If tooltip says "No active agent with this key is connected":

  1. Go to Settings → Agents
  2. Check that your agent shows "Running" status (not "Stopped")
  3. If stopped, check agent logs and network connectivity
  4. Resume or restart the agent service
  5. Wait for the heartbeat to reconnect

Datasource Shows Mixed Encryption Warning​

What it means: Some of the datasource's credentials are encrypted with one key, while others are encrypted with a different key. This typically happens when a re-encryption job fails partway through.

How to resolve:

  1. Go to Activities page and filter by type "Re-encryption"
  2. Find failed or incomplete jobs for this datasource
  3. Review the error details to understand what went wrong
  4. Fix the underlying issue (agent offline, network timeout, etc.)
  5. Retry key rotation to re-encrypt all credentials consistently

Why it matters: Datasources with mixed encryption may not connect properly because some credentials can't be decrypted.

Key Rotation Job Created But Datasources Still on Old Key​

What it means: The re-encryption job was created but hasn't completed successfully.

How to resolve:

  1. Go to Activities page and search for the job ID shown in the success message
  2. Check the job status and logs
  3. Common issues:
    • Agent offline - Ensure agent is running and connected
    • Permission error - Agent may need database access
    • Job timeout - Large number of datasources may take longer
  4. If the job failed, fix the underlying issue and click Rotate Keys again

I Have a Private Agent But Only See System Key​

What it means: Your agent hasn't been approved yet, or the key activation is pending.

How to resolve:

  1. Go to Settings → Agents
  2. Check if your agent status is "Registered" or "Pending Approval"
  3. Click Approve on the agent card
  4. Wait a few moments for the key to activate
  5. Refresh the Public Keys page (hard refresh: Cmd+Shift+R or Ctrl+Shift+R)
  6. Your private key should now appear in the list

Best Practices​

Deploy Private Keys for Production Environments​

Why:

  • Enhanced security with tenant-specific encryption
  • Private keys never leave your agent environment
  • Better data isolation from other customers
  • Meets compliance requirements (SOC 2, HIPAA, GDPR)

Recommended approach:

  • Production: Always use private keys (deploy SPCS agent)
  • Staging: Can use system key for cost savings
  • Development: System key is fine for testing

Migrate to Private Keys Early​

Best timing:

  • Migrate during initial setup before creating many datasources
  • Easier to migrate 5 datasources than 50
  • Reduces risk of mixed encryption scenarios

Migration process:

  1. Deploy private agent immediately after organization setup
  2. Approve agent to activate the key
  3. Click Rotate Keys to migrate any existing datasources
  4. Verify migration completed successfully
  5. Create new datasources (they'll use private key by default)

Monitor Key Versions Regularly​

What to check:

  • Review the "Latest Active Version" metric monthly
  • Ensure all datasources use the latest version
  • Identify keys with 0 datasources (candidates for cleanup)
  • Check for any keys stuck in "Pending Approval" state

Version tracking:

  • Higher version numbers indicate newer keys
  • Old versions should transition to "Historical" state
  • Active datasources should use the latest version

Handle Mixed Encryption Immediately​

Why it's critical:

  • Datasources with mixed encryption may fail to connect
  • Credentials are partially inaccessible
  • Indicates incomplete re-encryption

Action plan:

  1. Check Public Keys page daily for mixed encryption warnings
  2. Review Activities page for failed re-encryption jobs
  3. Retry rotation immediately to fix inconsistent state
  4. Don't create new datasources until mixed encryption is resolved

Plan Key Rotations During Maintenance Windows​

Timing considerations:

  • Re-encryption takes 1-2 minutes per 100 datasources
  • Schedule during low-activity periods (nights/weekends)
  • Avoid times when pipelines are actively running
  • Ensure your team is available to monitor

Communication:

  • Alert your data engineering team before rotation
  • Document the rotation in your change log
  • Monitor the Activities page during rotation
  • Verify completion before resuming normal operations
  • Agents - Deploy private agents that generate encryption keys
  • Settings - Settings overview
  • Activities - Monitor re-encryption job status and logs

Support​

Need help with encryption keys? Contact us at support@supa-flow.io

Last updated on by pungaa
AI Tools
Ask ChatGPTClaudeAsk Claude
On this page