# secrets (/docs/reference/api/secrets)

> Secrets are write-only: `put` hands a value to the configured secret store and returns its `secret://` reference and version, and no method ever reads a value back. Events and audit rows carry only the reference, name and version; values reach agents through the secret broker, never through the API. Methods are decided on `compute-tenant/{tenantId}`, or on `compute-fleet/global` for platform secrets with `scope: 'fleet'` in the root tenant. See [Security](/docs/operations/security) and [BMC credentials](/docs/guides/bare-metal/bmc).



Secrets are write-only: `put` hands a value to the configured secret store and returns its `secret://` reference and version, and no method ever reads a value back. Events and audit rows carry only the reference, name and version; values reach agents through the secret broker, never through the API. Methods are decided on `compute-tenant/{tenantId}`, or on `compute-fleet/global` for platform secrets with `scope: 'fleet'` in the root tenant. See [Security](/docs/operations/security) and [BMC credentials](/docs/guides/bare-metal/bmc).

All 2 methods are served by this release.

| Method              | Kind     | Authorization                                                                             | Phase | Status     |
| ------------------- | -------- | ----------------------------------------------------------------------------------------- | ----- | ---------- |
| [`put`](#put)       | mutation | `compute:secrets:manage` @ `compute-tenant` or `compute:secrets:manage` @ `compute-fleet` | v0.2  | registered |
| [`delete`](#delete) | mutation | `compute:secrets:manage` @ `compute-tenant` or `compute:secrets:manage` @ `compute-fleet` | v0.2  | registered |

## put [#put]

`POST /api/compute/secrets/put`

Stores a secret value under a name and returns its reference and version; a second put with the same name writes a new version.

The value is at most 64 KiB. A retry whose `idempotencyKey` equals the key of the put that wrote the current version returns that version and writes nothing; the key is not scoped to the calling identity. `scope: 'fleet'` outside the root tenant is `INVALID_INPUT`. The call is `UNAVAILABLE` when no secret store is configured, and `INVALID_STATE` when the existing secret lives in another store than the configured one.

Publishes `security.secret.put` with the reference, name and version, never the value.

* **Kind:** mutation
* **Authorization:** `compute:secrets:manage` @ `compute-tenant` or `compute:secrets:manage` @ `compute-fleet`
* **Module:** `server`
* **Phase:** v0.2 (registered)

**Input**

| Field            | Type                     | Required | Constraints                                                          |
| ---------------- | ------------------------ | -------- | -------------------------------------------------------------------- |
| `tenantId`       | string                   | yes      | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$`           |
| `name`           | string                   | yes      | at most 128 characters; matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` |
| `value`          | string                   | yes      | 1-65536 characters                                                   |
| `scope`          | one of `tenant`, `fleet` |          | default `"tenant"`                                                   |
| `idempotencyKey` | string                   | yes      | at most 128 characters; matches `^[A-Za-z0-9._~:/+=-]{1,128}$`       |

## delete [#delete]

`POST /api/compute/secrets/delete`

Deletes a secret's value from the store and its reference, returning `deleted: true`, or `deleted: false` when no such secret exists.

`scope: 'fleet'` outside the root tenant is `INVALID_INPUT`. The call is `UNAVAILABLE` when no secret store is configured, and `INVALID_STATE` when the secret lives in another store than the configured one. Publishes `security.secret.deleted`.

* **Kind:** mutation
* **Authorization:** `compute:secrets:manage` @ `compute-tenant` or `compute:secrets:manage` @ `compute-fleet`
* **Module:** `server`
* **Phase:** v0.2 (registered)

**Input**

| Field      | Type                     | Required | Constraints                                                          |
| ---------- | ------------------------ | -------- | -------------------------------------------------------------------- |
| `tenantId` | string                   | yes      | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$`           |
| `name`     | string                   | yes      | at most 128 characters; matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` |
| `scope`    | one of `tenant`, `fleet` |          | default `"tenant"`                                                   |