Structured secrets

What are structured secrets?

Structured secrets are secrets with multiple named fields instead of one flat string. A database credential, for example, can be stored as one secret with host, port, username, and password fields. An OAuth client configuration might use client_id, client_secret, and redirect_url.

The point is to keep values that belong together in one credential object while still letting application code address the parts by name.

How SikkerKey stores them

In SikkerKey, a structured secret's field values are serialized as a JSON object and encrypted as a single blob using the same envelope encryption model as standard secrets. The field names are stored as metadata so the dashboard can render labeled inputs and SDKs can expose field-aware helpers. The field values remain encrypted at rest.

Because the fields live inside one secret object, create, replace, rotate, version history, rollback, deletion, audit, and machine grants follow the same lifecycle as a standard secret. The difference is the multi-field shape and the ability to target individual fields for reads and rotation.

Creating a structured secret

When creating a structured secret in SikkerKey, the operator gives the secret a name and adds one row per field. Each field has a field name, a value, and, when automatic rotation is enabled, a rotate toggle.

Fields that are not marked for rotation keep their static value. Fields marked for rotation are generated by SikkerKey and then regenerated on the configured schedule. The rotation settings include interval, generated length, and charset.

That model fits common credentials where some fields are stable and one field is sensitive and replaceable. For a database credential, host, port, and username might stay static while password rotates every hour.

Common examples

Structured secrets are useful when a credential naturally has several related parts:

• Database credentials: host, port, database, username, password
• OAuth credentials: client_id, client_secret, redirect_url
• SMTP credentials: server, username, password
• TLS material: private_key, certificate
• Vendor account credentials: account_id, license_key

Keeping these fields together avoids spreading one logical credential across several unrelated secrets.

Reading structured secrets

SikkerKey SDKs expose structured secrets directly. Applications can fetch all fields or a single field without parsing JSON themselves:

creds = sk.get_fields("sk_db_prod")
host = creds["host"]
password = sk.get_field("sk_db_prod", "password")

The CLI follows the same idea: sikkerkey get sk_db_prod returns all fields as JSON, while sikkerkey get sk_db_prod password returns one field.

For environment injection and export, structured secrets are flattened into separate variable names, such as DB_CREDS_HOST, DB_CREDS_USERNAME, and DB_CREDS_PASSWORD.

Rotation

Structured secrets let operators rotate only the fields that should change. In a database credential, host and username may stay fixed while password rotates on a schedule. Each rotation still creates a new secret version, preserving rollback history for the full object.

SikkerKey also supports automatic rotation for structured secrets. Operators choose which fields rotate, the rotation interval, generated value length, and charset. Fields not marked for rotation stay static.

Access model

Structured fields are individually addressable for SDK reads and rotation settings, but the secret remains one access-controlled object. In SikkerKey's machine model, a machine must be approved, attached to the project, and explicitly granted the secret before it can read any field from it.

This keeps authorization simple: related values move through audit, grants, policies, and version history as one secret, while application code can still consume the exact field it needs.

Structured secrets vs flat secrets

A flat secret works well for one opaque value: an API key, signing key, token, password, or connection string. A structured secret works better when the credential is naturally a group of named parts.

You can encode structured data manually inside a flat secret, but then every consumer has to know how to parse it. A structured secret makes the field names part of the secret's metadata and gives SDKs a first-class way to read fields.