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

# Customer-managed encryption

> Choose how Corsa encrypts sensitive client data: Corsa-managed keys, BYOK with your own AWS KMS key, or HYOK with decryption in your own AWS account.

All data in Corsa is encrypted at rest (AES-256) and in transit (TLS 1.2+). On top of that, Corsa offers three encryption tiers for sensitive client fields such as names, contact details, and government ID numbers. Each tier gives you a different balance of control and product features.

***

## Encryption tiers

| | Corsa-managed (default) | BYOK (Tier 1) | HYOK (Tier 2) |
| - | - | - | - |
| **Who holds the key** | Corsa | You, in your AWS KMS | You, in your AWS KMS |
| **Where data is decrypted** | Corsa servers | Corsa servers, using your key for each use | In the browser of your authorized users, through the Secure Viewer hosted in your AWS account |
| **Your controls** | None needed | Kill switch (disable the key or revoke Corsa's access), key policy conditions, CloudTrail audit of every key use | Your own sign-in (passkeys), your decryptor group, your KMS key, your audit logs |
| **Product features** | All | All | Reduced on encrypted fields. See [features lost with HYOK](/hyok/limitations) |
| **What you run** | Nothing | One KMS key in your AWS account. The setup screen provides a key template prefilled for your workspace | A CloudFormation stack in your AWS account, installed from the app |
| **Can Corsa read the plaintext?** | Yes | Yes, while your key allows it | Corsa can't decrypt stored values. Some limits apply: see the [HYOK trust model](/hyok/index#trust-model) |

<Info>
  You choose **one tier per workspace**. Once a tier is active, you can't switch tiers or remove encrypted fields yourself. Contact your Corsa representative to plan a change.
</Info>

***

## Which tier to choose

<CardGroup cols={3}>
  <Card title="Corsa-managed" icon="shield">
    Choose this when standard encryption at rest meets your requirements. Every feature works, with no setup.
  </Card>

  <Card title="BYOK" icon="key" href="/encryption/byok">
    Choose this when you need to own the key, revoke Corsa's access at any time, and audit every use of the key, while keeping every feature, including fuzzy sanctions screening and AI.
  </Card>

  <Card title="HYOK" icon="lock" href="/hyok/index">
    Choose this when stored sensitive fields must stay unreadable to Corsa, and you accept exact-match-only screening and search on those fields.
  </Card>
</CardGroup>

Most regulatory frameworks, such as DORA, NYDFS Part 500 and ECB cloud guidance, require risk-based encryption and sound key management. They don't require you to hold the key yourself. BYOK covers most bank and auditor requirements for key ownership and revocation. HYOK adds customer-side decryption for the most sensitive fields.

***

## Fields you can encrypt

| Field group | Example fields | Corsa-managed | BYOK | HYOK |
| - | - | - | - | - |
| Names | `general.firstName`, `general.middleName`, `general.lastName`, `general.legalEntityName` | ✓ | ✓ | ✓ |
| Government ID and document numbers | `general.personalId` | ✓ | ✓ | ✓ |
| Contact details | `contact.emailAddress`, `contact.phoneNumber`, address lines, city, postal code | ✓ | ✓ | ✓ |
| Other fields | Financial estimates, free-text fields | ✓ | ✓ | Not eligible |

With HYOK, Corsa also rejects a field that a rule or workflow trigger uses in a non-equality condition, such as "contains", "starts with" or "greater than". Those conditions can't run on encrypted values.

Only workspace **Owners** can change the encryption configuration. Members with the **Support** role can view it.

***

## Check your encryption configuration

Use `GET /v1/platforms/encryption-config` to read the encryption configuration registered for your workspace. A `200` response returns the configuration. A `204 No Content` response means your workspace uses Corsa-managed encryption only.

<CodeGroup>
  ```bash REST API theme={null}
  curl -X GET "https://api.corsa.finance/v1/platforms/encryption-config" \
    -H "Authorization: Bearer <API_TOKEN>:<API_SECRET>"
  ```

  ```typescript Javascript theme={null}
  import { CorsaClient } from "@corsa-labs/sdk";

  const client = new CorsaClient({
    BASE: "https://api.corsa.finance",
    HEADERS: {
      Authorization: `Bearer ${process.env.API_TOKEN}:${process.env.API_SECRET}`,
    },
  });

  const config = await client.platform.getEncryptionConfiguration();
  console.log(config?.deploymentModel);
  ```

  ```python Python theme={null}
  import os
  from corsa_sdk import CorsaClient
  from corsa_sdk.api.platform import get_encryption_configuration

  client = CorsaClient(
      base_url="https://api.corsa.finance",
      token=f"{os.environ['API_TOKEN']}:{os.environ['API_SECRET']}",
  )

  response = get_encryption_configuration.sync_detailed(client=client)
  print(response.status_code, response.parsed)
  ```
</CodeGroup>

The response includes these fields:

| Field | Description |
| - | - |
| `deploymentModel` | `saas` (Corsa-managed), `byok` or `hyok` |
| `encryptionFieldsList` | The encrypted fields, per API operation |
| `setupStatus` | HYOK stack setup state, for example `ACTIVE` |
| `byokStatus` | BYOK key state: `pending_verification`, `active`, `revoked` or `error` |
| `byokKmsKeyArn`, `byokLastVerifiedAt`, `byokLastError` | BYOK key details and the result of the last verification |
| `healthStatus`, `lastHealthAt` | Last HYOK stack health check |
| `stackOutputs` | Non-secret HYOK stack outputs, including the PII public key (`piiPublicKeySpki`, `piiKeyId`) |

This endpoint reports the registered configuration. It doesn't test whether your KMS key or HYOK stack is reachable right now. Corsa checks that separately: see [BYOK verification](/encryption/byok#verify-the-key) and [HYOK health](/hyok/operations#health-checks).


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