> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesink.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions, audit and rotation

> Secret history, who touched what, and when a value is due to change.

## Versions

Giving a secret a new value does not overwrite the old one. It writes a new immutable version — numbered from 1, with its own ciphertext, nonce and wrapped key — and points the secret at it. Nothing is lost, and the previous value stays readable.

Renaming a secret or editing its description does **not** create a version. Only a new value does.

### Reading an older value

```bash theme={null}
sink pull prod --version 2
```

```http theme={null}
GET /secrets/{workspace_id}/{team_id}/{project_id}/{environment_id}/?version=2
```

This decrypts each secret at version 2 and returns the plaintext, exactly like a normal list.

<Warning>
  Version numbers count **per secret**. `?version=2` is not "the environment as it was" — it pins every secret to its own version 2, and a secret that has only ever been written once comes back at version 1. The CLI names the ones that fell back; over HTTP, compare each record's `current_version` against what you asked for.
</Warning>

### Listing versions

```http theme={null}
GET /secrets/{workspace_id}/{team_id}/{project_id}/{environment_id}/{secret_id}/versions
```

Returns every version of one secret, newest first. Note that this route hands back the stored **encrypted material** — `ciphertext`, `nonce` and the wrapped `dek` — not plaintext. It is there to show what history exists; use `?version=n` on the list route to actually read a value.

Version history is a paid capability; without it this route answers `402`. See [Plans and limits](/guides/plans).

## The audit log

Every secret carries a log of what has happened to it:

| Action     | Written when                                                                    |
| ---------- | ------------------------------------------------------------------------------- |
| `CREATED`  | The secret is created, singly or in bulk.                                       |
| `ACCESSED` | Its value is decrypted — by a read, a CLI pull, or a share link being redeemed. |
| `UPDATED`  | Its value, name or description changes.                                         |
| `DELETED`  | It is removed.                                                                  |
| `SHARED`   | It is included in a share link.                                                 |

```http theme={null}
GET /secrets/{workspace_id}/{team_id}/{project_id}/{environment_id}/{secret_id}/logs
```

Entries come back newest first, each with the action and the `actor_id` — the workspace membership that did it, which you can resolve against `GET /workspaces/{workspace_id}/members`.

<Note>
  A share redemption is attributed to the member who **created** the link, not to whoever opened it — the recipient is anonymous by construction. An `ACCESSED` entry against a secret that also has a recent `SHARED` entry is someone spending that link.
</Note>

Deleting a secret removes its log along with it. Export anything you need to keep before a deletion.

## Rotation

Every environment gets a rotation cadence when it is created — `default_policy`, in days, falling back to the deployment's default when you do not name one. Individual secrets can carry their own cadence, which wins over the environment's.

Each secret read reports both halves of the picture:

| Field             | Meaning                                                                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `last_rotated_at` | When the value last changed. `null` for secrets written before rotation tracking existed — fall back to `created_at`, which dates the original value. |
| `rotation_days`   | The cadence governing this secret: its own policy if it has one, otherwise its environment's.                                                         |

Rotation is advisory: Sink records the cadence and the last change so you can see what is overdue. It does not expire a secret or refuse to serve a stale one — the value keeps working until you replace it.

Rotating is just an update, which is to say a new version:

```bash theme={null}
sink push prod --file .env.rotated
```

or `PATCH` the single secret with its new value. The previous value stays in history, so a rollback is a `--version` away.