Connectors

How your token is protected

A connector holds an API token that can send email as your domain, so Plotwork guards it in two layers of encryption, with a key that belongs to your organisation alone and lives apart from the database. This page says what each layer stops, what it does not, and what you control.

TL;DR

Question	Answer
How is the token stored?	Sealed with AES-256-GCM under your organisation's own data key, as soon as it arrives. It is never stored in the clear.
Where is the data key?	In a separate key store, never in the database, itself sealed under a key only Plotwork's servers hold.
Is the data key shared?	No. Every organisation has its own random 256-bit key, made the first time it saves a connector.
Can anyone read the token back?	No. No page and no endpoint shows it, not to the owner, an admin or Plotwork support. Only its last four characters are shown, so you can tell which token is saved.
Can I replace the key?	Yes, at any time. Every connector's token is sealed again under a new key and the old key is destroyed.
What does removing a connector do?	It deletes that connector. Removing the last one, or deleting the organisation, destroys your organisation's data key, so no sealed token can ever be opened again by anyone (crypto-shredding).
Is it recorded?	Yes, every change in the organisation's audit log, never with the token.
Can the running service open the token?	Yes. It has to, to send your email when nobody is present. The layers protect against a leaked copy of storage, not against the running service.

The two layers

Layer	What it is	What it is bound to
1. The token	Your provider's API token, sealed with AES-256-GCM under your organisation's data key	Your organisation, the provider, and the version of the data key. A sealed token copied to another organisation or another provider, or kept past a key replacement, fails to open.
2. The data key	A random 256-bit key made for your organisation alone, kept in a separate key store and sealed with its own derivation of a key only Plotwork's servers hold	Your organisation and the key's version. A data key copied to another organisation, or rolled back to an older version, fails to open.

The sealed token is in the account database. The sealed data key is not: it is in a different store, Cloudflare's KV store, so the two halves are never in one place at rest.

What an attacker needs

They have	Can they read your token?
A copy of the database	No. The token is sealed, and your organisation's data key is not in the database.
The database and the servers' key	No. Your organisation's data key is in the other store.
The database, the servers' key and one organisation's data key	That organisation's token only. Each organisation has its own key, and a sealed token moved to another organisation fails to open.
All of them, after you removed your last connector or deleted the organisation	No. That destroyed your data key, and nothing can open a token again.

What the layers do not do

The connector must send your email when nobody is signed in, for example when an admin invites someone or a reminder goes out. So the running service can open your data key and your token, for the length of one send. It uses the token for that one request to your provider and puts it nowhere else: not in a log, not in an answer, not in the audit log.

The layers protect a copy of storage that leaked, a backup or a database export, not a compromise of the running service itself. If you need a token that no running service can ever use, do not set up a connector: your organisation's email then comes from Plotwork's address.

Your provider is the other place the token's power is limited. Make a token that can only send, and only for your domain where the provider allows it, so a token that leaked anyway could not read your mail or change your account. The provider pages say what each one offers.

Replace the key

An owner or admin can replace the organisation's data key at any time from the Connectors tab. Plotwork opens every connector's token with the current key, makes a new random key one version up, seals each token again under the new one, and the old key is gone with that write. The last four characters stay the same, because the token is the same.

Replacing the key is a good habit after someone with access to your infrastructure leaves, or on a schedule your policy sets. It does not change the token at your provider. To change the token itself, make a new one at your provider, paste it and save, then revoke the old one there.

If a token can no longer be opened, for example because the key was destroyed, replacing the key is refused and nothing changes. Paste a new token for that connector instead.

Remove a connector

Removing a connector deletes it. Removing the last one, or deleting the organisation, also destroys the organisation's data key. The sealed token may remain in a database backup for a time, but without the data key it is noise: nothing can open it, not Plotwork and not anyone with the backup. That is crypto-shredding.

When no connector is left, your organisation's email goes from Plotwork's address again at once. Removing a connector does not revoke the token at your provider, so revoke it there too.

Write-only tokens

Where	What you see
The Connectors tab	The provider, the From address, the last four characters of the token, the version of the data key, and when it was last tested
The API	The same fields. No endpoint answers the token.
The audit log	That the connector was set, whether the token changed, the provider and the From domain. Never the token.
Plotwork support	Nothing of the token.

To change a token, paste a new one. Leave the field empty when you edit other fields, and the saved token is kept.

Audit events

Every change is recorded in the organisation's audit log, with who made it and when:

Action	When	Details
`orgs.connector.set`	A connector is set up or changed	The provider, the From domain, whether the token changed, and whether it is the default
`orgs.connector.default`	A connector is made the default	The provider
`orgs.connector.test`	A test email is sent	The provider, whether it took it, and if not, why: the token, a refusal, or no answer
`orgs.connector.rotate`	The data key is replaced	How many tokens were sealed again
`orgs.connector.remove`	A connector is removed, and the key destroyed when it was the last	The provider
`orgs.security.reminder`	Reminders to turn on two-step sign-in are sent	How many were sent and how many skipped

On Enterprise these events can also go to your own tools as they happen. See Send audit events and drift to your tools.

Page	Why
Connectors	What a connector is, and which email goes through it
Email through your own domain	Setting one up
Audit log	Reading and exporting the events above
Privacy policy	What Plotwork stores for a connector, and for how long