Skip to main content

​
What is an Entity Secret?

The Entity Secret is a 32-byte private key designed to secure your developer-controlled wallets. It acts as your secret password, your personalized cryptographic stamp, known only to you. Circle’s platform does not store the Entity Secret. This ensures that only you can invoke private keys, maintaining complete control. It is therefore your responsibility to safeguard this secret.
Watch this video to help you build alongside our docs. Learn how to generate an Entity Secret, Fetch your Entity’s Public Key, generate the Entity Secret Ciphertext, and register the Entity Secret Ciphertext in the developer console.

​
What is an Entity Secret Ciphertext?

The Entity Secret is a token generated from your Entity Secret and Circle’s public key. This asymmetrically encrypted value is sent in API requests like wallet creation or transaction initiation to ensure critical actions are secure. This process enables secure usage of the Entity Secret, to ensure it cannot be easily accessed or misused.

​
How to Create and Register the Entity Secret

There are three options to register your Entity Secret:
  1. Use one of our server-side SDKs to generate the Entity Secret, encrypt it, and register it
  2. Generate the Entity Secret yourself by using Standard Libraries or CLI tools, then use the SDK to encrypt it and register it
  3. Generate the Entity Secret yourself by using Standard Libraries or CLI tools, encrypt it with the Entity public key to generate the Entity Secret Ciphertext, then register it in the Circle Console.
Option 1 provides the most streamlined experience since our SDK does the heavy lifting to manage the Entity Secret registration process. However, depending on your needs, you can selectively use Option 2 or 3 to generate and encrypt the entity secret directly.
The process to register your entity secret and create your first developer wallet is best laid out in our Register Your Entity Secret QuickStart and Create Your First Developer-Controlled Wallet Interactive Quickstart guides. Note: For any of the options above it is important to create a recovery file to ensure you can still have access to your funds in case you lose your entity secret. Option 1 above has this feature built-in already in our SDKs.

​
APIs Requiring Entity Secret Ciphertext

SummaryAPI
Create a new wallet setPOST /developer/walletSets
Create walletsPOST /developer/wallets
Create a transfer transactionPOST /developer/transactions/transfer
Accelerate a transactionPOST /developer/transactions/{id}/accelerate
Cancel a transactionPOST /transactions/{id}/cancel
Execute a contract transactionPOST /developer/transactions/contractExecution
Deploy a contractPOST /contracts/deploy
Deploy a contract from a templatePOST /templates/{id}/deploy

​
How to Rotate the Entity Secret

Periodic rotation of the Entity Secret enhances the overall security of developer-controlled wallets. Developers can initiate the Entity Secret rotation process when they possess the existing Entity Secret. To perform rotation, you will provide the system with the current Entity’s Secret Ciphertext and the newly created one. The system verifies the authenticity of the provided information before updating the Entity Secret. This process ensures that the Entity Secret remains fresh, reducing the risk of potential vulnerabilities associated with long-term use of the same secret. Additional Notes:
  • Entity Secret rotation takes immediate effect, rendering the old Entity Secret deprecated. As a result, ongoing API requests using the old Entity Secret will fail. Make sure to complete existing API requests before rotation, or reinitialize them following the entity secret rotation.
  • The existing Entity Secret Ciphertext does not need to be the same as the one registered as long as it is derived from the existing Entity Secret (encrypted and encoded). The newly created Entity Secret Ciphertext should be derived from a newly generated 32-byte entity secret to ensure security.
  • When the newly created Entity Secret is registered the previous recovery file will be deprecated, and a renewed recovery file can be downloaded for resetting the Entity Secret.

​
How to Reset the Entity Secret

Developers can initiate the Entity Secret reset process when an Entity Secret is compromised or lost. To ensure the security of the reset operation, developers need to upload the recovery file for authentication. After uploading the recovery file and entering the newly created Entity Secret Ciphertext into the system, the Entity Secret is reset, and a renewed recovery file can be downloaded Additional Notes:
  • Entity Secret reset takes immediate effect, rendering the old Entity Secret deprecated. As a result, ongoing API requests using the old Entity Secret will fail. Make sure to complete existing API requests before reset, or reinitializing them following the Entity Secret reset.
If both the Entity Secret and the recovery file are lost, you cannot create new developer-controlled wallets or initiate transactions from existing ones. Store both the Entity Secret string and the recovery file safely.
⌘I