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

# BYOK: bring your own AWS KMS key

> Encrypt sensitive client fields in Corsa with a symmetric AWS KMS key in your own account. Keep every feature, revoke access at any time, and audit each key use in CloudTrail.

With BYOK (Tier 1), Corsa encrypts your sensitive client fields with a key that you create and control in your own AWS account. Corsa decrypts on its servers only when your key policy allows it, so every product feature keeps working: rules, fuzzy sanctions and PEP screening, search, KYC integrations, AI features, and exports.

You keep three controls:

* **Kill switch.** Disable the key or remove Corsa's access, and Corsa can no longer decrypt or encrypt your protected fields.
* **Scoped access.** Your key policy only allows Corsa to use the key with your workspace's encryption context.
* **Audit.** AWS CloudTrail records every use of the key by Corsa, in your account.

<Note>
  BYOK protects your data with a key you own and can revoke. It doesn't hide plaintext from Corsa while access is granted: Corsa services read decrypted values to run screening, rules, and other features. If stored sensitive fields must stay unreadable to Corsa, see [HYOK](/hyok/index).
</Note>

***

## How it works

1. You create a symmetric AWS KMS key in your account. Its key policy grants Corsa's BYOK service role permission to use the key, only with the encryption context `platformId = <your workspace ID>`.
2. When a protected field is written through any path (API, SDK, KYC integration, or the app), Corsa's isolated encryption service asks your key for a data key and encrypts the field with AES-256-GCM. Each value is bound to its workspace, entity type, and field.
3. Corsa stores the encrypted value and a keyed search index. It never stores the plaintext of protected fields.
4. When an authorized Corsa user or service reads the field, the encryption service decrypts it with a data key that your KMS key unwraps.

Corsa caches decrypted data keys in memory for up to 5 minutes and reuses one data key per 5-minute window for new writes. This keeps latency low, and it bounds how long access continues after you revoke the key.

***

## Set up BYOK

You need an AWS account and permission to create a KMS key in it.

<Steps>
  <Step title="Start BYOK setup in Corsa">
    A workspace **Owner** opens **Settings** → **Encryption** and selects **BYOK**. Corsa shows your workspace ID (`platformId`), the Corsa BYOK role for your region, and the AWS region to use.
  </Step>

  <Step title="Create the key in your AWS account">
    The setup screen provides a key template prefilled for your workspace. Deploy it in the region shown. It creates a symmetric encrypt-and-decrypt key with the key policy Corsa needs. You can also create the key yourself, as long as its policy meets the [key policy requirements](#key-policy-requirements).
  </Step>

  <Step title="Register the key ARN">
    Paste the key ARN (for example `arn:aws:kms:us-east-1:111122223333:key/your-key-id`) into the setup screen. Key aliases aren't accepted.
  </Step>

  <Step title="Verify">
    Corsa runs an encrypt and decrypt round trip with your workspace's encryption context. On success, the key status becomes `active` and Corsa starts encrypting the fields you selected.
  </Step>
</Steps>

### Key policy requirements

Your key policy must allow the following:

* **Corsa use.** Corsa's BYOK role may encrypt, decrypt, and generate data keys with your key, but only when the encryption context `platformId` equals your workspace ID. So Corsa can use the key only for your workspace's data.
* **Corsa describe.** Corsa's BYOK role may describe the key, without an encryption context condition. KMS doesn't send an encryption context for this call. It lets Corsa confirm the key type, state, and region during verification.
* **Your administration.** Your own administrators keep full control, so they can manage, disable, and audit the key.

You can add stricter conditions, such as a VPC endpoint condition or a narrower principal, as long as Corsa's use is still allowed for your workspace ID. Test any change with the verification step.

<Warning>
  Don't schedule the key for deletion while BYOK is active. Data encrypted under a deleted key can't be recovered by you or by Corsa. Use **Disable key** as your kill switch instead: it's reversible.
</Warning>

***

## Verify the key

Corsa verifies the key when you register it, and monitors it afterwards. Verification encrypts and decrypts a test value with your workspace's encryption context and checks the key with `DescribeKey`.

| `byokStatus` | Meaning |
| - | - |
| `pending_verification` | Key ARN registered, verification not yet successful |
| `active` | Verification passed. Corsa encrypts and decrypts with your key |
| `revoked` | Your key is disabled, pending deletion, or Corsa's access was removed |
| `error` | Verification failed for another reason. See `byokLastError` |

You can read the status, `byokLastVerifiedAt`, and `byokLastError` with [`GET /v1/platforms/encryption-config`](/encryption/index#check-your-encryption-configuration).

***

## Revoke access (kill switch)

To stop Corsa from using your key, do any of the following in your AWS account:

* Disable the key (`aws kms disable-key --key-id <key-arn>`).
* Remove or change the Corsa statements in the key policy.
* Revoke any grant you created for the Corsa role.

After revocation:

* **Reads fail closed.** The app and API show protected fields as masked values with a **Key revoked** indicator. Corsa never falls back to a different key.
* **Writes of protected fields fail** with HTTP `423` and error code `KEY_REVOKED`. Writes that don't touch protected fields keep working.
* **Features that need the plaintext stop for protected fields**, including screening, rules that read those fields, search, and exports.
* **In-memory data keys expire within 5 minutes.** Until then, Corsa can still use data keys it unwrapped before revocation.
* **Corsa alerts you** and shows the revoked state in **Settings** → **Encryption**.

To restore access, re-enable the key or restore the policy. Corsa detects the change at the next verification and resumes normal operation. No data is lost while the key is disabled.

***

## Audit key use with CloudTrail

Every KMS call Corsa makes appears in your CloudTrail as a `GenerateDataKey`, `Decrypt`, `Encrypt`, or `DescribeKey` event. Filter by the Corsa BYOK role ARN to see them:

```bash theme={null}
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=ResourceName,AttributeValue=<key-arn> \
  --max-results 50
```

Each event records the caller role, the time, and the encryption context, including `platformId`. Because Corsa caches data keys for up to 5 minutes, one CloudTrail event can cover many field reads. CloudTrail shows when and how often Corsa used the key, not which individual record was read. Corsa's own audit log in the app records who viewed which client.

***

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| Verification fails with `AccessDeniedException` | The key policy doesn't name the Corsa BYOK role, or the `platformId` condition value is wrong | Copy both values again from **Settings** → **Encryption** and update the policy |
| Verification fails with `DisabledException` or `KMSInvalidStateException` | The key is disabled or pending deletion | Enable the key, or cancel the deletion |
| Verification fails with a region error | The key is in a different region from the one shown in setup | Create the key in the region shown in setup |
| Fields show **Key revoked** | Your key was disabled or Corsa's access was removed | Re-enable the key or restore the policy |
| Writes return `423 KEY_REVOKED` | Same as above | Same as above |
| Writes return `503` | Temporary KMS or network error | Retry with the same [idempotency key](/api/idempotency) |


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