Structured Secrets
Store related credentials as encrypted named fields, then manage machine access, field rotation, policies, versions, and recovery.
Structured secrets keep several related values together under one secret ID. Use named fields for credentials that are consumed as a set, such as a database host, port, username, and password or an OAuth client ID and client secret.
A structured secret is encrypted, granted, governed, versioned, and deleted as one secret. Machines can retrieve the full field map or select one field in an SDK, but access is granted to the complete structured secret.
#How structured secrets work
SikkerKey stores the fields as one encrypted JSON object. Field names remain available as metadata so the dashboard, CLI, and SDK can describe the structure without exposing field values.
Part | Purpose |
|---|---|
Secret name | Human-readable label for the complete credential set |
Secret ID | Stable identifier beginning with sk_ and followed by 16 letters and numbers |
Field names | Visible structure such as host, username, and password |
Field values | Encrypted values returned only to an authorized machine |
Version | Snapshot number for the complete field set |
Machine grant | Allows a machine to read the structured secret |
Access policy | Applies one set of read rules to the complete structured secret |
All field values are strings. The complete JSON value can be up to 12 KB. Field names must be unique within the secret.
#Create a structured secret
Select the project that should own the secret.
Open Secrets.
Select the plus button and choose Structured Secret.
Enter a secret name between 1 and 255 characters.
Enter a unique field name and its value.
Select Add field for each additional value.
Use the eye button to reveal or mask values while entering them.
Add an optional note.
Select Create Structured Secret.
The secret is created as version 1. Empty field rows are left out, so enter a value for every field that should belong to the structured secret. The Fields column shows how many field names are stored.
Use stable field names that match what the consuming application expects, such as host, port, username, and password. Changing a field name later requires creating the intended structure again.
#Create a rotating structured secret
Automatic rotation lets selected fields change on a schedule while the remaining fields stay static.
Open the New structured secret form and enter the secret name.
Add every required field.
Enable Automatic rotation.
Mark at least one field to rotate.
Enter values for every field that will remain static.
Choose a rotation interval from 5 minutes to 30 days.
Choose Random or UUID generation.
For Random, select a length from 8 to 128 characters and the character groups to use.
Create the rotating secret.
Rotating fields receive server-generated values at creation. Static fields use the values you entered. Each scheduled rotation generates new values only for the selected rotating fields, preserves the static fields, and creates the next version of the complete object.
#Copy a new structured secret across an application
When the project belongs to an application, the creation flow can copy the structured secret to selected sibling environment projects.
Create the secret in Prod, Staging, or Dev.
At the copy prompt, select the additional environments.
Review any warning that the same secret name already exists in a target project.
Select Confirm, or select Skip to keep it only in the current project.
Each environment receives its own secret ID, encryption, versions, grants, policy, and lifecycle. For a static structured secret, the field values are copied as entered. For a rotating structured secret, each environment generates and rotates its own selected field values. Frozen projects are not offered as targets.
#Review structured-secret metadata
Structured secrets appear in the same project table as other machine-readable secrets. The structured type marker and Fields count distinguish them from standard single-value secrets.
Column | Meaning |
|---|---|
Name | Editable secret name and structured type |
ID | Stable secret ID with a copy button |
Note | Editable description |
Fields | Number of field names in the structure |
Ver | Current version of the complete object |
Machines | Number of machines granted the structured secret |
Policy | Attached policy, or no policy |
Updated | Most recent metadata or value change |
Last read | Most recent successful machine read, or Never |
Search by name, ID, or note. Sort by name, update time, or last-read time. Stored field values remain hidden.
#Replace field values
Open the secret’s row menu and select Configure.
Open Value.
Select each field that will be included in the replacement.
Enter the new values.
Use the eye button to reveal or mask values while entering them.
Select Replace value.
The replacement becomes a new version of the structured object and receives fresh encryption. Include every field and value that the current structure should contain. The dashboard does not display or prefill the stored plaintext.
Treat replacement as writing the complete intended field set. If the schema itself needs different field names, create a new structured secret with the new structure and move machine access to it.
#Rotate selected fields once
Manual rotation generates new values for selected fields while preserving every unselected field.
Open Configure, then Value.
In Rotate, choose Random or UUID.
Choose the generated length and character groups when using Random.
Select the fields to rotate.
Select Rotate selected.
The selected fields change together in one new version. Machine grants, policy binding, name, note, secret ID, and unselected field values remain unchanged.
#Manage automatic field rotation
Open Schedule to enable rotation for an existing structured secret or manage its current schedule. Choose the fields that should rotate, the cadence, and the generated-value shape.
Save schedule applies changes to the interval, selected fields, or generated-value shape.
Pause rotation stops scheduled changes while keeping the configuration.
Resume rotation restarts the schedule.
The status shows the latest completed rotation and the next scheduled rotation.
Each completed rotation preserves unselected fields and creates a complete new version.
Use the schedule to manage value changes while a rotation schedule exists. Version restoration and manual replacement are available for structured secrets without a schedule.
#Review and restore versions
Version history records the initial field set and every replacement, manual rotation, scheduled rotation, and restoration. The list shows version numbers and timestamps without revealing values.
Open the secret’s row menu and select History.
Open Versions.
Find the earlier complete field set you want to use.
Select Restore.
Restoring copies that encrypted field set into a new current version. Newer history remains intact. For example, restoring version 3 while version 9 is current creates version 10.
#Grant machine access and attach a policy
Add the machine to the project, then configure the machine and grant the structured secret. The grant allows the machine to retrieve the complete field set.
Use the Policy column to attach one project policy. Time windows, source-address rules, rate limits, co-signing, lifetime limits, and read-count rotation are evaluated for each read of the structured secret. Select No policy to remove the binding.
#Delete and restore a structured secret
Deleting moves the structured secret to Trash for 30 days. The secret becomes unavailable immediately, and its machine grants and rotation schedule are removed.
Open the row menu and select Delete, or select several secrets for bulk deletion.
Review the machines that will lose access.
Confirm the deletion.
Trash keeps the encrypted current field set, secret ID, name, original project, and version history during the recovery window. Restore it to the original project, then reapply machine grants and any required rotation settings.
Permanent deletion from Trash, or cleanup after 30 days, removes the structured secret and every retained version.
#Permissions
Permission | Access provided |
|---|---|
Project in scope | View structured-secret metadata, field names, versions, policy, machine count, and activity |
Manage structured secrets | Create, rename, update, rotate, restore versions, and delete structured secrets |
Configure machine grants | Choose which project secrets a machine can read |
Manage policies | Attach, remove, and configure policies according to the role’s policy capabilities |
Manage own Trash | Restore or permanently delete structured secrets the member deleted |
Manage all Trash | Manage every deleted secret in the vault |
Vault owners receive full access. Organization members receive project scope and structured-secret capabilities through their access role. Trash access comes from the vault role.
#Troubleshoot structured secrets
Symptom | What to check |
|---|---|
Create button is unavailable | Enter a name, use unique field names, and provide at least one field value. For rotation, select a rotating field and fill every static field. |
Expected field is missing | Confirm it had a value when the secret was created or included in the complete replacement field set. |
Get field reports not found | Check the exact field name and capitalization shown in the secret metadata. |
Machine receives Access denied | Confirm the machine is approved, belongs to the project, and has a grant for the structured secret. |
Machine read is blocked | Review the attached policy and the project’s freeze status. |
Only one field should be visible to a machine | Store that value in a separate secret and grant the machine that secret instead. |
Manual replacement or version restore fails | Check whether the secret has a rotation schedule and manage changes through the schedule. |
Copied environment has different rotating values | Each application environment generates and manages its rotating fields independently. |