# secrets-api

## Pages

- [Secrets API](https://docs.ezghcloud.com/secrets-api/index.md) — Secrets hold named fields in immutable numbered versions, envelope-encrypted at rest. Every path is under an organization; lists are paged with limit, cursor and nextCursor.
- [Read one field of a version](https://docs.ezghcloud.com/secrets-api/AccessSecretField/index.md) — One field's value, as written. Billed as one operation. A field the version doesn't have is 404.
- [Read a version's values](https://docs.ezghcloud.com/secrets-api/AccessSecretVersion/index.md) — Every field's value, as written. Needs secrets.versions.access, which the read-only policies don't grant. Billed as one operation and recorded in Trails without values. A destroyed version is 404 with error.details.reason "destroyed". The response is never cacheable.
- [Create a secret](https://docs.ezghcloud.com/secrets-api/CreateSecret/index.md) — With fields, version 1 is created in the same request (which also needs secrets.versions.create) and latestVersion is 1; without, the secret has no versions. The body may be up to 16 MiB. A name already taken in the project is 409 secret_name_taken. The response never carries a value.
- [Grant an EZGH product access to a secret](https://docs.ezghcloud.com/secrets-api/CreateSecretGrant/index.md) — Lets one product (consumer) read the secret for one of its resources (consumerResource, a resource name in the secret's organization of a type that product uses secrets for). version is "latest" (default) or a number. Needs secrets.grants.create and secrets.versions.access on the secret, so nobody can grant more than they could read. A second grant for the same consumer and resource is 409 grant_exists; while grants are switched off the answer is 409 grants_unavailable. Uses an Idempotency-Key.
- [Add a version to a secret](https://docs.ezghcloud.com/secrets-api/CreateSecretVersion/index.md) — Either the whole new field set (fields), or a base version with set and remove applied (base may be "latest"), so a rotation can change one field without reading the others. Removing a field that isn't in the base is 400; a base that doesn't exist or was destroyed is 404, and one destroyed while the write was in flight is 409 conflict, as is a version written concurrently: retry. The body may be up to 16 MiB. The response is the new version's metadata, never a value.
- [Delete a secret](https://docs.ezghcloud.com/secrets-api/DeleteSecret/index.md) — Irreversible: the secret, its versions, their values and its grants are erased at once.
- [Revoke a grant](https://docs.ezghcloud.com/secrets-api/DeleteSecretGrant/index.md) — Takes effect on the product's next resolve. Releases one grant allocation.
- [Destroy a version](https://docs.ezghcloud.com/secrets-api/DestroySecretVersion/index.md) — Irreversible: the version's fields are deleted at once and its metadata stays, state destroyed. Destroying a destroyed version changes nothing. If it was latest, latest moves to the highest enabled version (or none). Releases one enabled-version allocation. No request body.
- [Get a secret's metadata](https://docs.ezghcloud.com/secrets-api/GetSecret/index.md) — Never a value: read values from a version.
- [Get a grant](https://docs.ezghcloud.com/secrets-api/GetSecretGrant/index.md)
- [Get a version's metadata](https://docs.ezghcloud.com/secrets-api/GetSecretVersion/index.md) — Field names, never values. A version that doesn't exist (or latest of a secret with none) is 404.
- [List a secret's grants, newest first](https://docs.ezghcloud.com/secrets-api/ListSecretGrants/index.md) — At most 1000 grants.
- [List a secret's versions, newest first](https://docs.ezghcloud.com/secrets-api/ListSecretVersions/index.md) — Metadata and field names only, never a value. Destroyed versions are listed, with no field names.
- [List a project's secrets, newest first](https://docs.ezghcloud.com/secrets-api/ListSecrets/index.md) — Metadata only, never a value. name finds one secret by its name.
- [Change a secret's description and tags](https://docs.ezghcloud.com/secrets-api/UpdateSecret/index.md) — Every field is optional, and only the ones given change.
- [CreateSecretGrantRequest](https://docs.ezghcloud.com/secrets-api/schemas/CreateSecretGrantRequest/index.md)
- [CreateSecretRequest](https://docs.ezghcloud.com/secrets-api/schemas/CreateSecretRequest/index.md)
- [CreateSecretVersionRequest](https://docs.ezghcloud.com/secrets-api/schemas/CreateSecretVersionRequest/index.md) — Exactly one of: fields; or base, with set and remove.
- [Error](https://docs.ezghcloud.com/secrets-api/schemas/Error/index.md) — Every non-2xx answer. Clients branch on code, never on message.
- [FieldValue](https://docs.ezghcloud.com/secrets-api/schemas/FieldValue/index.md) — A field's value: text, or bytes as {"base64": …}. At most 8192 bytes once decoded; it comes back in the form it was written.
- [Fields](https://docs.ezghcloud.com/secrets-api/schemas/Fields/index.md) — Field names to values: at most 1000 fields, names matching ^[A-Za-z_][A-Za-z0-9_.-]{0,255}$ (names aren't secret; values are).
- [QuotaExceeded](https://docs.ezghcloud.com/secrets-api/schemas/QuotaExceeded/index.md) — quota_exceeded: the quota that refused the request. Never with Retry-After.
- [Secret](https://docs.ezghcloud.com/secrets-api/schemas/Secret/index.md) — A secret's metadata. Never a value.
- [SecretFieldValue](https://docs.ezghcloud.com/secrets-api/schemas/SecretFieldValue/index.md)
- [SecretGrant](https://docs.ezghcloud.com/secrets-api/schemas/SecretGrant/index.md) — Lets one EZGH product read a secret for one of its resources.
- [SecretGrantList](https://docs.ezghcloud.com/secrets-api/schemas/SecretGrantList/index.md)
- [SecretList](https://docs.ezghcloud.com/secrets-api/schemas/SecretList/index.md)
- [SecretName](https://docs.ezghcloud.com/secrets-api/schemas/SecretName/index.md) — Unique in the project.
- [SecretValue](https://docs.ezghcloud.com/secrets-api/schemas/SecretValue/index.md)
- [SecretVersion](https://docs.ezghcloud.com/secrets-api/schemas/SecretVersion/index.md) — A version's metadata. Never a value.
- [SecretVersionList](https://docs.ezghcloud.com/secrets-api/schemas/SecretVersionList/index.md)
- [Tags](https://docs.ezghcloud.com/secrets-api/schemas/Tags/index.md) — At most 50; keys 1-128 characters, values at most 256, keys starting with ezgh: are reserved.
- [UpdateSecretRequest](https://docs.ezghcloud.com/secrets-api/schemas/UpdateSecretRequest/index.md)
- [VersionRef](https://docs.ezghcloud.com/secrets-api/schemas/VersionRef/index.md) — A version number, or "latest".