Customer-managed keys

Customer-managed keys are for an Enterprise team on the hosted service. Only an owner or an administrator sees the control or can change it. A member sees nothing of it, and a Team plan or a personal organisation has no such control.

What this does for you

Your organisation's data is encrypted under one organisation key. Normally the service's own key protects that organisation key. With this control, a key in your own EU key service protects it instead. Every read of your organisation's data then needs your key. If you disable your key, nobody can open that data, the service included, until you enable it again.

Before you start

• You are an owner or an administrator of an Enterprise team, on Organisation → Security.
• You have a symmetric encryption key in your key service, in an EU region: eu-central-1, eu-west-1, eu-west-3, eu-north-1, eu-south-1 or eu-south-2. London (eu-west-2) and Zurich (eu-central-2) are outside the EU and are refused.
• Your key's policy lets the service's principal use Encrypt and Decrypt on it. Ask support for the principal's name. Limit that grant with the condition kms:EncryptionContext:org equal to your organisation id, which the page shows under the key field. The principal is the same for every customer, so this condition is what stops another organisation from pointing its own data at your key.
• You have the key's full ARN (arn:aws:kms:<region>:<account>:key/<id>). An alias is refused, because an alias can later be pointed at another key.

Steps

1. Open Organisation → Security. Under Customer-managed key, paste the key's ARN into Key reference and choose Check and save.
2. The service tests the key first: it encrypts a random value with your key and decrypts it again. If that fails, the save is refused with the reason (for example DisabledException or AccessDeniedException) and nothing is stored.
3. If the test passes, your organisation key is moved under your key. Your data itself is not re-encrypted: the same organisation key opens it, and only your key can now unlock that organisation key. The page then shows In force: and the ARN.
4. To move back, choose Go back to the platform's key. The organisation key is moved under the service's own key again, and your data stays readable.

Each save, change and removal is written to the audit log as org.customer_key_changed, with the key before and after. Each refused save, and each read your key refused, is listed under Key events on the same page, with who did it, the key and the reason. The key material itself is never written down.

When you disable or revoke your key

• From the next read, your organisation's data cannot be opened. A page that cannot load tells members "Your organisation's key is unavailable" instead of a general error, and the API answers 503 unavailable.
• Other organisations are not affected.
• Nothing is deleted. Enable the key again and access comes back, with nothing lost.
• While your key is disabled you cannot remove or change the setting, because the organisation key can only be moved while it can be opened.

Limits

• Deleting your key, or letting its scheduled deletion finish, makes your organisation's data unreadable for good. The service cannot recover it.
• A read that has already opened the organisation key finishes. Disabling stops the next one.
• What this protects is the data sealed under your organisation key: messages, credentials, connector tokens, audit details and the run history. Names and settings that are stored unencrypted are not covered.
• The self-hosted edition does not have this control. It keeps its own master key.