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

# Encrypt HYOK fields with the SDK

> Encrypt HYOK fields on your side before they reach Corsa, using the Node.js SDK with a public key you pin from your own AWS account.

When you send client data through the API, encrypt HYOK fields before they leave your systems. The Node.js SDK does this for you. It encrypts each configured field with a fresh data key, wraps the data key with your HYOK public key, and computes the normalized hash that Corsa uses for exact search and screening. Corsa never receives the plaintext.

You don't need any credential for your HYOK stack to encrypt. Encryption uses only the **public** half of your HYOK key.

***

## Pin your public key

Take the public key from your own AWS account, not from Corsa. This way, nobody can substitute a different key without you noticing.

```bash theme={null}
aws kms get-public-key \
  --key-id <your-hyok-key-arn> \
  --query PublicKey --output text > hyok-public-key.b64

# Fingerprint to pin
base64 -d hyok-public-key.b64 | sha256sum
```

**Settings** → **Encryption** shows your HYOK key ARN. Corsa also shows the same public key and its fingerprint there (`stackOutputs.piiPublicKeySpki` and `piiKeyId`). Check that the fingerprints match.

***

## Configure the client

<CodeGroup>
  ```typescript Javascript theme={null}
  import { EncryptedCorsaClient } from "@corsa-labs/sdk";

  const client = EncryptedCorsaClient.withEncryptedFields(
    {
      baseUrl: "https://api.corsa.finance",
      apiKey: `${process.env.CORSA_API_TOKEN}:${process.env.CORSA_API_SECRET}`,
      publicKey: {
        spkiBase64: process.env.CORSA_HYOK_PUBLIC_KEY_SPKI, // contents of hyok-public-key.b64
        keyId: process.env.CORSA_HYOK_KEY_ID,               // your HYOK key ARN
      },
      // Optional: fail if the configured key doesn't have this SHA-256 fingerprint
      expectedKeySpkiSha256: process.env.CORSA_HYOK_KEY_SHA256,
    },
    encryptedFieldSchema // the same field list as your workspace's encryptionFieldsList
  );

  await client.individualClients.createIndividualClient({
    general: { firstName: "Jane", lastName: "Doe", personalId: "AB1234567" },
    contact: { emailAddress: "jane.doe@example.com" },
  });
  // firstName, lastName, personalId and emailAddress leave your process encrypted
  ```

  ```bash REST API theme={null}
  # Without the SDK, each protected field must already be an encrypted envelope
  # (prefix __enc__) produced with the envelope v2 format and your public key.
  curl -X POST "https://api.corsa.finance/v1/clients/individuals" \
    -H "Authorization: Bearer <API_TOKEN>:<API_SECRET>" \
    -H "Content-Type: application/json" \
    -d '{
      "general": {
        "firstName": "__enc__eyJ2ZXJzaW9uIjoy...",
        "lastName": "__enc__eyJ2ZXJzaW9uIjoy..."
      }
    }'
  ```

  ```python Python theme={null}
  # The Python SDK doesn't encrypt HYOK fields yet.
  # Send protected fields through the Node.js SDK, a Corsa KYC integration,
  # or manual entry in the app. Plaintext for protected fields is rejected.
  ```
</CodeGroup>

***

## What the SDK sends

For each protected field, the SDK sends an envelope (version 2) that contains:

* the value encrypted with AES-256-GCM under a random 256-bit data key;
* the data key wrapped with RSA-OAEP-SHA256 under your public key, together with the field's resource (`corsa:v2:<platformId>:<entityType>:<fieldPath>`);
* the key ID;
* `hashData`: the SHA-256 of the [normalized value](/hyok/limitations#how-values-are-normalized-for-search).

Corsa turns `hashData` into the stored keyed index with your workspace's salt. Corsa can't decrypt the value.

Reading values back through the API returns the envelopes. Decrypt them for your users in the Secure Viewer. Server-side decryption outside your Secure Viewer isn't supported.

***

## Migrating from the previous SDK setup

Earlier versions configured `apiSecret` and `encryptionServiceUrl` for an encryption credential. HYOK no longer uses machine credentials for encryption. Replace them with `publicKey`, and delete any SDK secrets you created in your HYOK stack.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.