> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How the entity secret works

> Learn how the entity secret secures developer-controlled wallets and how it is used in API requests.

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](https://github.com/circlefin/w3s-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](/sdks/developer-controlled-wallets-nodejs-sdk) or
  [Python SDK](/sdks/developer-controlled-wallets-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](https://console.circle.com/) 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](https://console.circle.com/).

* **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](https://console.circle.com/). After a reset, the old entity
  secret is invalidated immediately and a new recovery file is generated.

<Warning>
  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.
</Warning>