Developer-controlled wallets depend on a single developer-held cryptographic
key: the entity secret. Because Circle never stores it, you retain exclusive
control over your wallets and bear sole responsibility for its security.
The entity secret and ciphertext
These two terms are distinct but inseparable: the entity secret is the key
itself, and the ciphertext is the encrypted form you send in API requests.
Entity secret
The entity secret is a randomly generated 32-byte private key that authorizes
sensitive wallet operations under your Circle account.
What to know:
- Scoped to your Circle account, not to individual API keys. API keys
authenticate requests; the entity secret authorizes the wallet operations
those requests perform.
- Circle never stores a copy. Only you can authorize operations on your
developer-controlled wallets.
- Losing it without a recovery file means permanent loss of access to your
wallets and funds.
Entity secret ciphertext
The entity secret ciphertext is the encrypted form of the entity secret, passed
as entitySecretCiphertext in API request bodies.
What to know:
- Produced by encrypting the entity secret with Circle’s public RSA key before
each request. Circle decrypts it server-side to verify authenticity and
authorize the operation. For the encryption implementation, see the
entity secret sample code
on GitHub.
- Each ciphertext is single-use. Reusing one causes the request to be rejected,
which prevents replay attacks.
- When you use the
Circle Node.js SDK or
Python SDK, re-encryption
happens automatically before every call. If you make direct API calls without
an SDK, you are responsible for re-encrypting for each request.
The recovery file
When you register your entity secret, Circle generates a recovery file tied to
that secret. The recovery file is the only mechanism for resetting your entity
secret through Circle Console if it is ever lost.
What to know:
- Without the recovery file, there is no path to recover access to your
developer-controlled wallets or the funds they hold.
- The recovery file is invalidated each time you rotate your entity secret. Each
rotation produces a new one. Storing an old recovery file after rotation
provides no protection.
Best practices
-
Store the entity secret securely. Use a secrets manager, hardware security
module (HSM), or encrypted password manager. Never commit the entity secret to
version control, include it in application configuration files, or allow it to
appear in logs.
-
Save the recovery file immediately after registration. The recovery file
can only be downloaded once, during the registration flow. If you skip this
step, you must rotate your entity secret to generate a new one. Store it in a
separate, secure location from the entity secret itself.
-
Rotate periodically. Rotating the entity secret limits exposure if it is
ever silently compromised. Rotate on a regular schedule, such as every 180
days. Rotation takes effect immediately. Any in-flight API requests using the
old entity secret will fail. Plan rotations during low-traffic periods and
reinitialize pending requests afterward. Rotate in
Circle Console.
-
Reset if compromised or lost. If your entity secret is lost or you suspect
it has been compromised, use your recovery file to reset it in
Circle Console. After a reset, the old entity
secret is invalidated immediately and a new recovery file is generated.
If both the entity secret and the recovery file are lost, you cannot create
new developer-controlled wallets or initiate transactions from existing
wallets. There is no recovery path. Store both in separate, secure locations.
