Entity Secret
The Entity Secret is a public-private key pair that secures all developer-controlled operations in UTXOS. It encrypts wallet private keys and signs sponsorship transactions.
UTXOS does not store your Entity Secret private key. If you lose it, you permanently lose access to all associated wallets and sponsorships. There is no recovery option.
What is the Entity Secret used for?
| Feature | How Entity Secret Is Used |
|---|---|
| Developer-controlled wallets | Encrypts wallet private keys so only you can access them |
| Transaction sponsorship | Signs transactions from your sponsorship wallet |
| Future features | Any developer-controlled operation requiring cryptographic security |
How does the Entity Secret work?
- You generate a public-private key pair in the dashboard
- UTXOS stores only the public key
- Wallet creation uses your public key to encrypt wallet private keys
- Your SDK uses your private key to decrypt and sign
This means:
- UTXOS cannot access your wallet funds
- Only someone with your private key can sign transactions
- Your private key never leaves your infrastructure
Generate an Entity Secret
Navigate to security settings
Go to Dashboard > Project Settings > Security.
Generate the key pair
Click Generate Key Pair to create your Entity Secret.
Download the private key
Immediately download and securely store the private key. This is your only opportunity to save it.
Verify storage
The public key is now displayed in your dashboard and will be used to encrypt future wallets.
Download your private key immediately after generation. You cannot retrieve it later from the dashboard.
Storage Best Practices
Do
| Practice | Why |
|---|---|
| Store in a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) | Centralized, audited, access-controlled |
| Use environment variables on servers | Keeps secrets out of code |
| Create encrypted backups in multiple secure locations | Prevents permanent loss |
| Restrict access to authorized personnel only | Limits exposure |
| Audit access logs regularly | Detects unauthorized access |
Do Not
| Practice | Why |
|---|---|
| Commit to version control | Git history is permanent and often public |
| Store in plaintext files | No encryption or access control |
| Include in client-side code | Exposes to all users |
| Share via email or chat | Insecure transmission, creates copies |
| Store on personal devices | Not backed up, not access-controlled |
Environment Variable Setup
Add your Entity Secret private key as an environment variable:
# .env (server-side only)
UTXOS_PRIVATE_KEY=your_entity_secret_private_keyThen use it in your SDK initialization:
import { Web3Sdk } from "@utxos/sdk";
const sdk = new Web3Sdk({
projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
apiKey: process.env.UTXOS_API_KEY,
privateKey: process.env.UTXOS_PRIVATE_KEY, // Entity Secret
network: "testnet",
});Never expose UTXOS_PRIVATE_KEY to client-side code. It must only exist on your secure backend servers.
Key Rotation
If you suspect your Entity Secret is compromised:
Generate a new Entity Secret
Create a new key pair in the dashboard. This does not affect existing wallets.
Migrate wallets
Existing wallets remain encrypted with the old key. To migrate:
- Retrieve each wallet using the old private key
- Create new wallets using the new Entity Secret
- Transfer funds from old wallets to new wallets
- Update your database with new wallet IDs
Update your infrastructure
Deploy the new private key to your servers and remove the old one.
Revoke old key
Once migration is complete, the old key is no longer needed. Securely delete all copies.
Automatic key rotation without fund migration is not currently supported. All existing wallets must be manually migrated if you rotate keys.
Compromise Response
If your Entity Secret is compromised:
- Immediately transfer funds from all affected wallets to new wallets (created with a new Entity Secret)
- Generate a new Entity Secret in the dashboard
- Investigate the breach to understand how it occurred
- Review access logs for any unauthorized activity
- Update infrastructure with new credentials
- Notify stakeholders if user funds were at risk
Multiple Entity Secrets
Each UTXOS project has one Entity Secret. If you need separate secrets for different environments:
| Environment | Recommendation |
|---|---|
| Development | Create a separate UTXOS project with its own Entity Secret |
| Staging | Create a separate UTXOS project with its own Entity Secret |
| Production | Use your production project’s Entity Secret |
This provides complete isolation between environments.
Security Audit Checklist
Use this checklist to verify your Entity Secret security:
- Private key stored in a secrets manager
- Private key not in version control
- Private key not accessible to client-side code
- Encrypted backup exists in a separate secure location
- Access restricted to authorized personnel
- Access logs are being monitored
- Incident response plan documented
Next Steps
- Developer-Controlled Wallets - Use your Entity Secret
- Transaction Sponsorship - Sign sponsorship transactions
- Whitelist URLs - Additional security configuration