Entity Secret Management

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.

Our 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.

The Entity Secret Ciphertext is a RSA encryption 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.

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.

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.

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:

• Currently, 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.

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.

WHAT'S NEXT

Jump back into creating your first Developer-Controlled Wallet!

• Create Your First Wallet