Shared secrets#
A credential that two people need — a staging database password, an API token for a third-party service, a licence key — usually ends up in a chat message, a pinned comment or a spreadsheet, where it stays readable by everybody forever and nobody can say who has seen it.
Secrets in the sidebar is the alternative. You save the value once, choose who else may read it, and every reading of it is recorded.
Save one#
Open Secrets and click New secret. It takes:
- a name, up to 120 characters — the thing your colleague will search for, so "Staging database password" rather than "pw2";
- what it is for, optional, up to 500 characters, shown beside the name in the list;
- the value, up to 8,192 characters. That is enough for a private key in PEM form; it is not somewhere to paste a database dump.
Names have to be unique among your secrets in the workspace — saving a second "Staging database password" is refused rather than silently making two. Two different people can each have one by that name.
You can keep 200 secrets in a workspace. Anybody in the workspace can save one, whatever their role: this is not an admin feature.
Read one#
Click a secret, then Reveal. The value appears in a field you can copy from, and:
- it is hidden again after two minutes, and immediately if you switch workspace or press the eye button;
- every reveal is written to the audit log, with your name and the time — a reveal that nobody can see happening is the thing this feature exists to replace;
- you can reveal up to 60 times an hour.
Nothing else ever returns the value. Lists, search and the API all give you the name, the owner and when it last changed, and only the reveal hands over what is inside.
Share it#
Open the secret you own and pick a colleague under Shared with. They can be anybody active in the same workspace, up to 50 people per secret. The list shows whether each person has read it or has not read it yet.
Somebody a secret is shared with can do exactly two things: reveal it, and Remove my access. They cannot rename it, replace the value, delete it or pass it on — a recipient who could re-share is a recipient who can undo your revocation without it showing anywhere.
To take access back, remove the person from Shared with. Do it because they no longer need it; do it and rotate the value if you think they should never have had it, since a value that has been revealed has been read.
The workspace is the boundary. A secret can only be shared with people in the workspace it was saved in, so it cannot be used to move a credential out to somebody the workspace's admins have never heard of.
Replace or delete it#
As the owner:
- Rotate replaces the value in place. Everybody it is shared with gets the new value the next time they reveal, with nothing to re-send, and Last changed moves — which is the first thing you want to know after a leak. Renaming a secret or editing its description does not move that date.
- Delete secret removes it for everybody. The value cannot be recovered: secrets do not go to Trash.
Who can see what#
| Can | Owner | Shared with | Everybody else, admins included |
|---|---|---|---|
| See that the secret exists | Yes | Yes | No |
| Reveal the value | Yes | Yes | No |
| Rename it, or replace the value | Yes | No | No |
| Choose who it is shared with | Yes | No | No |
| Give up their own access | — | Yes | — |
| Delete it | Yes | No | No |
A workspace owner or admin cannot read your secrets. An admin reaches every
board in the workspace, and quietly extending that to every credential anybody
has stored is exactly what would stop this being used for the case it exists
for. What an admin does see is the audit log: secret.created,
secret.updated, secret.rotated, secret.shared, secret.unshared,
secret.revealed and secret.deleted, each naming the secret and the person,
never the value or its length.
Sessions only — no API keys#
A secret can only be read from a signed-in session. An
API key gets a 401 on every /secrets
route, service accounts included, and a service account cannot be given a secret
at all.
A key is a credential left on a machine so an agent can run unattended, which is the opposite of the threat model here: one stolen key would otherwise be every secret its owner can read, silently. Give an agent its own credential in the system that issues it, and use a secret to hand that credential to a person.
When somebody leaves#
Access is re-checked against the workspace on every request, so deactivating or removing somebody stops them reading any secret in that workspace immediately — there is nothing to remember to revoke.
Removing somebody also deletes the sharing rows on both sides: the secrets they were given, and their name in the Shared with list of secrets they own. The secrets they created stay, sealed to the workspace and readable by nobody, so they are still there if the person is ever re-added.
If the person who left was the only one who could read a credential your team needs, treat it as lost and rotate it at the source.
How it is stored#
Values are encrypted with AES-256-GCM before they are written down, under a key that is not in the database, and each one is bound to the workspace and the secret it belongs to — so a value lifted from a backup and dropped into another row will not decrypt. Keys are versioned, and a value re-seals itself under the current key the next time it is read.
Secrets are not in the ⌘K search, not in a board's CSV export, and not in a workspace export. The whole point is that the value leaves by one audited door.
Where the limits are#
| Limit | Value |
|---|---|
| Secrets you can keep in a workspace | 200 |
| People one secret can be shared with | 50 |
| Length of a value | 8,192 characters |
| Length of a name | 120 characters |
| Length of the description | 500 characters |
| Reveals | 60 an hour |
| A revealed value stays on screen | 2 minutes |
Every route is listed under Shared secrets in the API reference, which is where the exact errors live — though as above, a key cannot call any of them.