Register Your Entity Secret

Learn to create an Entity Secret and register its ciphertext to enable developer-wallet functionality.

In this guide you will learn how to generate, encrypt, and register an Entity Secret. You can use standard libraries for generating and encrypting the Entity Secret, or SDK methods to simplify your development journey. Likewise, for registering an Entity Secret Ciphertext, you can use an SDK method or the Circle Console.

Prerequisites

1. Create a Developer Account and acquire an API key in the Console.
2. Install the applicable server-side SDK for your language - needed for 1a, 2a, 3a below.

Introduction

The Entity Secret is a randomly generated 32-byte key designed to enhance security in developer-controlled wallets. After being generated, the hex-encoded Entity Secret key is encrypted into ciphertext for greater data safety. Later on, to create a wallet or to perform a transaction, you must append the Entity Secret ciphertext to the API request arguments. The ciphertext must be re-encrypted (rotated) whenever an API requires it.

1. Generate an Entity Secret

There are two ways to generate an Entity Secret: using the SDK, or using standard libraries or CLI tools. Once generated the Entity Secret will consist of a 32-byte hex string value similar to: 7ae43b03d7e48795cbf39ddad2f58dc8e186eb3d2dab3a5ec5bb3b33946639a4.

Remember to keep your Entity Secret safe and store it securely, for instance in your password manager, to ensure access to your developer-controlled wallet. Although creating a ciphertext is not required for Entity Secret registration using a server-side SDK, it is still important to store and keep the Entity Secret for future API calls.

1a. Generate Entity Secret Using the SDK

You can use the SDK methods below to generate an Entity Secret.

Node.js SDK

import { generateEntitySecret } from "@circle-fin/developer-controlled-wallets";

// This will print out a new entity secret and sample code to register the entity secret
generateEntitySecret();

The above code generates an Entity Secret and displays it on your terminal screen. Make sure to save your Entity Secret since you will use it in the following steps.

1b. Generate Entity Secret Using Standard Libraries

You can also use standard libraries or CLI tools to generate the Entity Secret. Below are a few examples.

Shell

openssl rand -hex 32

The Entity Secret is displayed on your terminal screen. Make sure to save your Entity Secret since you will use it in the following steps.

2. Encrypt the Entity Secret

Note: If you use an SDK method to register the Entity Secret, then this step is optional - see step 3a. Register the Entity Secret Using the SDK below.

Similarly, you can encrypt the Entity Secret in two ways to generate the Entity Secret Ciphertext: using the SDK, or manually using standard libraries.

2a. Encrypt Entity Secret Using the SDK

You can use the SDK methods below to generate the Entity Secret Ciphertext.

Node.js SDK

import { generateEntitySecretCiphertext } from "@circle-fin/developer-controlled-wallets";

async function main() {
  await generateEntitySecretCiphertext({
    apiKey: "<your-api-key>",
    entitySecret: "<entity-secret>",
  });
}

main()[OR];

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const developerSDK = initiateDeveloperControlledWalletsClient({
  apiKey: "<your-api-key>",
  entitySecret: "<entity-secret>",
});

const entitySecretCiphertext =
  await developerSDK.generateEntitySecretCiphertext();
console.log(entitySecretCiphertext);

2b. Encrypt Entity Secret Using Standard Libraries

Similarly, you can create the Entity Secret Ciphertext using standard libraries or CLI tools. To that end, you must first retrieve your Entity Secret’s public key. The public key plays a crucial role in generating the Entity Secret Ciphertext in the upcoming step. To obtain the required public key, initiate a request to the Get public key for entity API endpoint. Remember, this endpoint can be accessed by providing your valid API key for authentication.

Node.js SDK

// Import and configure the developer-controlled wallet SDK
const {
  initiateDeveloperControlledWalletsClient,
} = require("@circle-fin/developer-controlled-wallets");
const circleDeveloperSdk = initiateDeveloperControlledWalletsClient({
  apiKey: "<API_KEY>",
  entitySecret: "<ENTITY_SECRET>", // Make sure to enter the entity secret from the step above.
});

const response = await circleDeveloperSdk.getPublicKey({});

Response Body

{
  "data": {
    "publicKey": "-----BEGIN RSA PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAsL4dzMMQX8pYbiyj0g5H\nFGwdygAA2xDm2VquY8Sk0xlOC0yKr+rqUrqnZCj09vLuXbg1BreO/BP4F4GEIHgR\nBNT+o5Q8k0OqxLXmcm5sz6CPlsFCom+MiOj6s7RD0SXg91WF8MrN88GyN53xkemA\nOYU1AlIt4dVIrFyGY8aQ57sbWHyIjim+do1kBX+svIA/FLHG/sycoGiPU1E+Kydf\nlEDga4iR2DSbW6Zte9cGDg9Ivw/seNd0TLzJz6oC9XgSK5Et6/ZpOmqJgvISQ6rT\nK15DJ8EzIOzZZuEVOefgy1S7rLdSH7DexuR4W7T+KpP/f8Px0bxd4N6MT5V5kBYa\ngYHHIvqlJvXe5EzwidIWk1rg1X+YJt2M48h3Pr9HeECcmrnEYOgp32m/9lJ8vKp9\nhNh0rEKww/ULd1HqCEm/I0QGuji13XcGxVo5+7KCb/C76CNdW3pdRMn6fwFh4WVu\nu99iRc9OZhlkphysWm44hs1ZPpMCAkKttWjhnLZwIatN27x2JUqoCEUOho19iT+F\nwlPFA7E0Ju9Rqm68AkCXxHsJsAuGT8m6FLQZLHv4JyO/QEVzD7vY08A2I5dz1mVt\ngVam1/05Axju6poRomx/DUxiR0QH1+0Kg15+2A0fRkBggTTn7kvGsgz0cqk9cTm0\nEITpIVGcSGrVNRrmSye2OW0CAwEAAQ==\n-----END RSA PUBLIC KEY-----\n"
  }
}

Once you have the public key, you will use RSA to encrypt your Entity Secret and generate its ciphertext. Immediately after, you will transform this encrypted data into a Base64 format. The output ciphertext will be exactly 684 characters long.

Node.js

const forge = require("node-forge");

const entitySecret = forge.util.hexToBytes("YOUR_ENTITY_SECRET");
const publicKey = forge.pki.publicKeyFromPem("YOUR_PUBLIC_KEY");
const encryptedData = publicKey.encrypt(entitySecret, "RSA-OAEP", {
  md: forge.md.sha256.create(),
  mgf1: {
    md: forge.md.sha256.create(),
  },
});

console.log(forge.util.encode64(encryptedData));

Note: You can also refer to the provided sample code for encrypting and encoding the Entity Secret.

3. Register the Entity Secret

Finally, you can register your Entity Secret in two ways: using the SDK, or using the Circle Console.

Caution: It is important to store a recovery file in case the Entity Secret is lost. Such a recovery file can then be used to reset your Entity Secret. You can optionally specify the path to store the recovery file when you register your Entity Secret.

Note: Circle’s platform does not store the Entity Secret, meaning only you can invoke private keys. However, it also means that you must save the Entity Secret yourself to ensure the security and accessibility of your developer-controlled wallets.

3a. Register the Entity Secret Using the SDK

Note: If you use the SDK to register, then this step accepts the unencrypted Entity Secret directly. Therefore, step 2. Encrypt the Entity Secret above would not be required.

You can use the SDK methods below to register your Entity Secret.

Node.js SDK

import { registerEntitySecretCiphertext } from "@circle-fin/developer-controlled-wallets";

registerEntitySecretCiphertext({
  apiKey: "",
  entitySecret: "",
  recoveryFileDownloadPath: "",
});

Now that the Entity Secret has been registered, make sure to read and follow some Final Considerations.

3b. Register the Entity Secret Ciphertext Using the Console

You can also register the Entity Secret Ciphertext within the Circle Console. You need to register the ciphertext in the console only once by following the steps below.

1. Access the Configurator Page in the Circle Console.
2. Enter the Entity Secret Ciphertext generated in the previous step.
3. Click Register to complete the Entity Secret Ciphertext registration.

Final Considerations

Note: You must re-encrypt the Entity Secret to create a new ciphertext for each API request.

Circle’s APIs Requiring Entity Secret Ciphertext enforces a different Entity Secret Ciphertext for each API request. One-time use of Entity Secret Ciphertext tokens ensures that even if an attacker captures the ciphertext from a previous communication, they cannot exploit it in subsequent interactions.

Caution: Using the same Ciphertext for multiple requests will lead to rejection.

To create a different Entity Secret Ciphertext token, repeat step 2. Encrypt the Entity Secret. As long as the Entity Secret Ciphertext comes from the same registered Entity Secret, it will be valid for subsequent API requests.

Note: If you use the server-side SDK for API requests, you will only need to configure the Entity Secret using the SDK. The SDK will then handle the creation of a new ciphertext for each API request.

Next Steps

You have successfully registered your entity secret! Jump into the next guide, where you will learn how to:

1. Create your first developer-controlled wallet
2. Rotate and Reset Entity Secret: Check out how you can rotate and reset your Entity Secret.