---
title: "Concepts"
description: "Secrets, fields, versions and latest, how values are encrypted, and what deleting a secret erases."
---

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

# Concepts

## Secrets, fields and versions

| Term | Meaning |
| --- | --- |
| Secret | A named collection of fields in a project. Secrets are regional resources (`us-west-1`) with an ID, an `sec_` slug and a resource name. The name is yours and is unique in the project. |
| Field | A name and a value. A secret's version holds any number of fields, up to 1,000. |
| Version | One immutable snapshot of a secret's fields, numbered from 1. A version is `enabled` or `destroyed`. |
| `latest` | The highest-numbered enabled version. A secret with no enabled version has no `latest`, and reading it is `404`. |
| Grant | Permission for one EZGH product to read a secret for one of its resources. See [Grants](/secrets/grants). |

A secret's name is up to 128 characters: letters, digits, `_`, `.`, `/` and `-`, starting with a
letter or digit, such as `prod/db`. Description and tags are optional, and you can change them at
any time. Nothing else about a secret changes: to change a value, you write a new version.

### Fields

- A field name is up to 256 characters: letters, digits, `_`, `.` and `-`, starting with a letter
  or `_`. Names are case-sensitive.
- A value is text (UTF-8) or binary, up to 8 KiB (8,192 bytes) after decoding. An empty value is
  allowed. In the API a binary value is `{ "base64": "..." }`, and you get it back in the form you
  wrote it.

> **Caution**
>
> Field names aren't confidential. They're stored unencrypted, shown in the console, returned to
> anyone who can read the secret's metadata, and recorded in Trails and in error messages. Never put
> a secret in a field name. Only values are encrypted.

### Versions

A write creates a version, either as the complete set of fields, or as changes to an existing
version: take version 3 (or `latest`), set some fields and remove others. Changing one field
this way doesn't need the writer to read the rest.

- Versions never change. Readers read `latest` or pin a number, and an old version stays readable
  until you destroy it.
- Destroying a version erases its values at once and keeps its record, with the state
  `destroyed`. Destroying `latest` makes the next lower enabled version `latest`. A destroyed
  version can't be read again, by anyone; reading it is `404` with
  `error.details.reason: "destroyed"`.
- A secret can have up to 100,000 enabled versions. Nothing is destroyed automatically, and you
  pay for the fields of every enabled version, so destroy versions you no longer need.
- Writes that race for the same version number fail with `409 conflict`: run the write again.
  Send `If-Match` with the secret's `ETag` to make a write succeed only if the secret hasn't
  changed.

## Encryption

Values are encrypted at rest with envelope encryption:

- Every secret has its own data key. Each version's values are encrypted with a key derived from
  it, and the data key is stored only in encrypted form, itself encrypted by a key-encryption key.
- Key-encryption keys are rotated every 90 days. Rotation re-encrypts data keys and doesn't
  interrupt reads or writes.
- Key-encryption keys are encrypted by a root key that is kept outside the database, in the
  platform's secret store.
- Values are never written to logs, error messages or Trails, and API responses that contain
  values are marked `Cache-Control: no-store`.

You don't manage keys. Encryption at rest protects stored data: anyone your policies allow to
read a value receives it in clear text over HTTPS, so grant `secrets.versions.access` carefully.

## Deleting secrets and versions

- **Destroying a version** erases its values immediately.
- **Deleting a secret** erases every version's values, its data key, its versions and its grants
  immediately. It can't be undone and has no recovery window.
- **Deleting a project or your organization** erases the secrets it contains within minutes.

## Where secrets are read

Two kinds of reader use Secrets:

- **Your workloads**: applications, CI and the `ezgh` CLI, calling the API with an API key, a CLI
  login or a console session. IAM is checked on every request.
- **EZGH products** that you've given a [grant](/secrets/grants).

Each read you make of a value is a billed read, and [Trails](/secrets#trails) records every
read, including the products'. Reads by products through a grant aren't billed.

Source: https://docs.ezghcloud.com/secrets/concepts/index.mdx