Use the API

All paths are under https://secrets.ezghcloud.com/v1/organizations/{organizationId}/projects/{projectId}. {secretId} is the secret’s ID (a UUID), and {version} is a number or latest. The examples use $BASE for that prefix and an API key. Lists are paged as described in Requests.

Create a secret

curl -X POST "$BASE/secrets" \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod/db",
    "description": "Production database",
    "tags": { "team": "data" },
    "fields": { "DB_USER": "app", "DB_PASSWORD": "s3cret", "CA_CERT": { "base64": "LS0tLS1CRUdJTi..." } }
  }'

201 returns the secret: id, slug, name, resourceName, latestVersion (a number, or null for a secret created without fields), versionCount, fieldCount (the fields in enabled versions, which is what you’re billed for), grantCount and the timestamps. A secret is never returned with a value. With fields, version 1 is created with the secret, which needs secrets.versions.create as well as secrets.secrets.create. A name that’s taken is 409 secret_name_taken. The create accepts an Idempotency-Key.

Write a version

A version is either the complete set of fields (this one becomes version 2):

curl -X POST "$BASE/secrets/$SECRET_ID/versions" \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "DB_USER": "app", "DB_PASSWORD": "s3cret", "OLD_KEY": "x" } }'

or changes to an existing version, which keeps every field you don’t mention. This one builds on latest and becomes version 3:

curl -X POST "$BASE/secrets/$SECRET_ID/versions" \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "base": "latest", "set": { "DB_PASSWORD": "n3w-s3cret" }, "remove": ["OLD_KEY"] }'

Send exactly one of fields or base. base is a version number or "latest". Removing a field the base doesn’t have is 400. 201 returns the new version’s metadata:

{
  "number": 3,
  "state": "enabled",
  "fieldNames": ["DB_PASSWORD", "DB_USER"],
  "fieldCount": 2,
  "createdBy": { "type": "Bot", "userName": "deployer" },
  "createdAt": "2026-10-02T09:58:02.114Z",
  "destroyedAt": null
}

(createdBy is the full Trails userIdentity.) Add If-Match with the secret’s ETag to write only if the secret hasn’t changed (412 precondition_failed otherwise). A write that races another for the same version number is 409 conflict: run it again. At the enabled versions quota, a write is 409 quota_exceeded: destroy versions you no longer need.

Read values

All the fields of a version:

curl "$BASE/secrets/$SECRET_ID/versions/latest/value" \
  -H "Authorization: Bearer $EZGH_API_KEY"

{ "version": 3, "fields": { "DB_USER": "app", "DB_PASSWORD": "n3w-s3cret" } }

One field, at .../versions/{version}/fields/{field}, returns { "version": 3, "name": "DB_PASSWORD", "value": "n3w-s3cret" }. A text value is a string and a binary value is { "base64": "..." }.

Each of these calls is one billed read and is recorded in Trails. Read all the fields of a version in one call rather than one call per field. A secret without an enabled version, an unknown field or a destroyed version is 404; for a destroyed version the error has error.details.reason: "destroyed".

Destroy a version

curl -X POST "$BASE/secrets/$SECRET_ID/versions/2/destroy" \
  -H "Authorization: Bearer $EZGH_API_KEY"

returns 200 with the version, state destroyed. Destroying a version that’s already destroyed returns 200 with the version and changes nothing.

Errors

Errors use the standard error body. In addition to 401, 403 and 404: