---
title: "Secrets"
description: "Store passwords, API keys, certificates and .env files as encrypted, versioned secrets, and read them from your applications."
---

> 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.

# Secrets

EZGH Secrets stores sensitive values, such as database passwords, API keys, certificates and the
contents of a `.env` file. A secret holds named fields, and every change writes a new, immutable
version. Values are encrypted at rest. Your applications, CI and the `ezgh` CLI read them over the
API, and IAM decides who may.

- [Concepts](/secrets/concepts) — Secrets, fields, versions, encryption and deletion.
- [Use the API](/secrets/api) — Create secrets, write versions and read values.
- [CLI guide](/secrets/cli) — Work with .env files and binary values from the command line.
- [Grants](/secrets/grants) — Let an EZGH product read a secret without handing it the value.
- [Pricing and limits](/secrets/pricing-and-limits) — What fields, reads and writes cost, and the quotas and limits that apply.

The Secrets API is at `https://secrets.ezghcloud.com`. In the console, open **Secrets** for the
current project. The `ezgh secrets` commands cover the same tasks.

## Fields in the console

When you create a secret or a new version in the console, enter its fields in one of two ways:

| Mode | What you enter |
| --- | --- |
| Key/value | One field per row: a name and a value. Select **Binary (base64)** for a value given as base64. |
| Plaintext | A `.env` file, or a JSON object. |

Plaintext `.env` is read the same way as `ezgh secrets create --from-env-file`: `KEY=VALUE` lines,
with `#` comments, an optional `export ` prefix, and single- or double-quoted values that may span
lines. If a name appears twice, the last value is used. Every value is text.

A JSON object maps field names to values: `{ "DB_USER": "app", "PORT": 5432 }`. Numbers and
`true`/`false` are stored as text. For a binary value, give `{ "base64": "…" }`.

Switching from Key/value to Plaintext shows your fields as JSON. The review step lists field
names, never values.

## Permissions

| Action | Allows | `SecretsFullAccess` | `SecretsReadOnlyAccess` | `SecretsDataAccess` | `ReadOnlyAccess` |
| --- | --- | --- | --- | --- | --- |
| `secrets.secrets.list` | List a project's secrets | Yes | Yes | Yes | Yes |
| `secrets.secrets.create` | Create secrets in a project | Yes | No | No | No |
| `secrets.secrets.get` | Read a secret's metadata | Yes | Yes | Yes | Yes |
| `secrets.secrets.update` | Change a secret's description and tags | Yes | No | No | No |
| `secrets.secrets.delete` | Delete a secret | Yes | No | No | No |
| `secrets.versions.create` | Write new versions | Yes | No | No | No |
| `secrets.versions.list` | List a secret's versions | Yes | Yes | No | Yes |
| `secrets.versions.get` | Read a version's field names | Yes | Yes | Yes | Yes |
| `secrets.versions.access` | Read values | Yes | No | Yes | No |
| `secrets.versions.destroy` | Destroy versions | Yes | No | No | No |
| `secrets.grants.create` | Let an EZGH product read a secret | Yes | No | No | No |
| `secrets.grants.list` | List a secret's grants | Yes | Yes | No | Yes |
| `secrets.grants.get` | Read a grant | Yes | Yes | No | Yes |
| `secrets.grants.delete` | Revoke a grant | Yes | No | No | No |

- `secrets.versions.access` is the only action that returns values. Everything else shows names
  and metadata. `SecretsReadOnlyAccess` and `ReadOnlyAccess` never reveal a value.
- `SecretsDataAccess` is for workloads that only read values: it covers `secrets.secrets.list`,
  `secrets.secrets.get` and `secrets.versions.get` (names and metadata, so a workload can find a
  secret by name, as `ezgh secrets read <name>` does) and `secrets.versions.access`.
- Creating a secret with `fields` needs `secrets.versions.create` as well as
  `secrets.secrets.create`.
- Creating a grant needs `secrets.grants.create` **and** `secrets.versions.access` on the secret,
  so nobody can give a product more than they could read themselves.
- `AdministratorAccess` and the root user can do all of these. API keys act with their owner's
  access.
- `secrets.secrets.list` and `secrets.secrets.create` apply to a project. The other actions
  apply to a secret, so a custom policy can limit them to one secret or a pattern by resource
  name, such as `ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:sec_*`. See [IAM](/iam).

## Trails

Secrets calls are recorded in [Trails](/trails) with the event source `secrets.ezghcloud.com`,
under the same rules as every other API. `eventName` is the operation:

| Operation | `eventName` |
| --- | --- |
| List, create, read, update and delete secrets | `ListSecrets`, `CreateSecret`, `GetSecret`, `UpdateSecret`, `DeleteSecret` |
| Write, list and read versions | `CreateSecretVersion`, `ListSecretVersions`, `GetSecretVersion` |
| Read a version's values | `AccessSecretVersion` |
| Read one field | `AccessSecretField` |
| Destroy a version | `DestroySecretVersion` |
| Create, list, read and revoke grants | `CreateSecretGrant`, `ListSecretGrants`, `GetSecretGrant`, `DeleteSecretGrant` |

- Reads of values are recorded with `readOnly` `true`. Each is an `AccessSecretVersion` or
  `AccessSecretField` event that shows who read it, when, and which version. A single-field read
  records the field's name. Other reads (`ListSecrets`, `GetSecret`, `ListSecretVersions`,
  `GetSecretVersion`, `ListSecretGrants`, `GetSecretGrant`) aren't recorded, like reads in
  every other API ([what Trails records](/trails#what-trails-records)).
- Values are never recorded, and neither are the names of the fields you set. A create
  records the secret's name, description and tags, and the number of fields when you give `fields`.
  A version write records how it was made (all
  fields, or changes to a base), the base, the number of fields, and the names of fields you
  remove. The `responseElements` hold identifiers only.
- When an EZGH product reads a secret through a [grant](/secrets/grants#trails), the read is
  recorded as `ResolveSecret`.

```sh
ezgh trails events --event-source secrets.ezghcloud.com --event-name AccessSecretVersion --from 1d
```

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