Secret API

Creates a protected secret and its initial revision.

Send name, type, value, and permitted consumer references. Supported types include credential, tls_certificate, and approved provider-specific structures. Each type validates its own value shape.

An empty consumers array creates protected secret metadata without authorizing an integration to resolve it. Use this when the intended consumer does not exist yet. Create that resource, then authorize its consumer ID before running its connection test. The example assumes bkd_archive already exists.

To register an S3 credential for approved backup consumers, send:

{
  "name": "backup-destination-access",
  "type": "credential",
  "value": { "access_key": "ACCESS_KEY_ID", "secret_key": "SECRET_ACCESS_KEY" },
  "consumers": [{ "type": "backup_destination", "id": "bkd_archive" }]
}

Replace the following:

• ACCESS_KEY_ID: the access-key ID issued by the object-storage provider.
• SECRET_ACCESS_KEY: its corresponding secret, supplied through your approved secret-management process.

Returns 201 with secret ID and revision metadata, excluding the submitted value. An unapproved consumer or invalid credential structure returns 422; TLS secret validation additionally checks key and certificate compatibility.

Returns type, name, revision IDs, consumer references, and rotation status. Requires secrets:read. No query flag converts this endpoint into a plaintext retrieval API.

A resource configuration read can expose the secret reference without granting secret administration. This allows operators to inspect why an integration is failing without distributing its credential to every resource viewer.

Updates the display name or permitted consumers. Requires the current secret ETag in If-Match. A supplied consumers array replaces the complete set; omission preserves it, an empty array removes future consumer authorization, and null is rejected. Every consumer must exist in the permitted scope.

Returns 200 with secret metadata and its updated revision, excluding the value. Changing consumers does not rotate the credential or revoke material already used by an accepted operation. Inspect active consumer work before retiring provider credentials.

Publishes a complete replacement secret revision.

Requires secrets:write, If-Match, and a complete new value. Omitted subfields are not copied implicitly from the old credential. Validation failure leaves the active revision unchanged.

Publishing the revision returns 201 without confirming consumer adoption. Apply it through the consumer's credential configuration, then inspect consumer adoption. Secret rotation links the backup-destination and TLS-listener procedures.

Returns requested and observed secret revision for each consumer.

Do not revoke the previous external credential until required consumers adopt the replacement and active transfers finish. A successful secret write is not a successful backup destination login.

Deletes a secret when its consumer and recovery references permit removal.

Requires the current secret ETag. Active consumers or retained recovery requirements return 409 secret_in_use with reference IDs. Detach or replace the references before retrying. Ordinary secret deletion does not revoke the credential at its issuing provider.

For an exposure, follow credential exposure response to revoke provider access, replace the consumer credential, and inspect affected operations. TLS listener rotation describes certificate adoption; volume encryption covers storage keys.