Store and read a secret

This guide walks through the lifecycle of a secret: creating the container, writing its value as a version, reading the metadata back, and rotating to a new version.

Before you begin

• Authentication. Export an API token as $QIBDO_API_TOKEN. Every path is relative to https://api.qibdo.example.com. See Authenticate a user and manage the session.
• Permissions. Your identity needs permission to manage vault secrets in the workspace. See the authorization model.
• Prerequisites. A workspace UUID. Throughout, {workspace} is your workspace UUID.

Your deployment’s API domain

api.qibdo.example.com is an example host. qibdo runs on your own infrastructure, so the API lives at your deployment’s own domain. Replace it with yours before running these examples.

Console

Coming soon

A step-by-step walkthrough in the qibdo console is on the way. For now, use the REST tab.

CLI

Coming soon

A qibdo CLI walkthrough is on the way. For now, use the REST tab.

REST

1. Create the secret container

Create a named container with a POST. The name must be unique in the workspace (lowercase letters, digits, slashes, hyphens, and underscores). No value is supplied yet, so the container starts empty; you can optionally set a rotation period and key-value tags.

POST /vault/v1/workspaces/{workspace}/engines/qibdo/secrets HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN
Content-Type: application/json

{ "name": "billing/stripe-api-key" }

The call completes synchronously and returns an operation already done, with the new secret’s id in its resource_id.

2. Add a value

The container holds nothing until you append a version. Send the secret bytes base64-encoded in the payload field. Read the value from an environment variable so it never lands in shell history or a committed file:

SECRET_ID="f47ac10b-58cc-4372-a567-0e02b2c3d479"
PAYLOAD_B64="$(printf '%s' "$STRIPE_API_KEY" | base64)"

curl -sS -X POST \
  "https://api.qibdo.example.com/vault/v1/workspaces/$WORKSPACE/engines/qibdo/secrets/$SECRET_ID:addVersion" \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"payload\": \"$PAYLOAD_B64\"}"

This appends the first version and makes it the current value immediately.

3. Read the metadata

A GET on the secret returns metadata only, its name, rotation period, tags, and timestamps. The value itself is never returned here; it stays in the engine and is read through version-scoped reads.

GET /vault/v1/workspaces/{workspace}/engines/qibdo/secrets/f47ac10b-58cc-4372-a567-0e02b2c3d479 HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN

To list the secrets in a workspace, GET the collection; it is paginated and supports filtering and ordering.

4. Rotate to a new value

When the value changes, append another version rather than editing the old one, since versions are immutable:

POST /vault/v1/workspaces/{workspace}/engines/qibdo/secrets/f47ac10b-58cc-4372-a567-0e02b2c3d479:addVersion HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN
Content-Type: application/json

{ "payload": "<base64 of the new value>" }

The new version becomes the current value; the previous one stays readable by its version number until you disable or destroy it.

Next steps

• See secret and crypto key versioning for the version state model.
• Apply the security baseline for secret-handling rules.