Skip to main content
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.
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.

​
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.
1

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

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

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

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.

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

​
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. You can read the status, byokLastVerifiedAt, and byokLastError with GET /v1/platforms/encryption-config.

​
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:
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