---
title: Shared secrets
description: Hand a colleague a credential without pasting it into a chat — who can read a secret, what a reveal records, and what happens when somebody leaves.
section: Workspaces and access
order: 5
---

# 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](/docs/administration/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](/docs/workspaces-and-access/api-keys) 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](/docs/administration/members-and-offboarding)
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](/docs/boards-and-tickets/search), not in a
board's CSV export, and not in a
[workspace export](/docs/administration/export-and-deletion). 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](/docs/agents-and-api/api-reference), which
is where the exact errors live — though as above, a key cannot call any of them.