Secrets concepts
The secrets model has two resources: a secret type that defines validation and sensitivity, and a secret that stores a value under that type. This page explains how they relate, how scope resolves a value, and which fields cannot change after creation.
Resource model
A secret always references one secret type. The type supplies the validation schema for the value and the sensitivity level that decides how the value is stored.
Secret types
A secret type is a named definition with a validation schema and a sensitivity level. Two fields are fixed once the type exists:
- The sensitivity level cannot change after creation.
- The type classification (
systemorcustom) cannot change after creation.
A custom type can be updated (name, description, schema) and deleted when no
secret uses it. A system type cannot be deleted. A type that any secret
references cannot be deleted until those secrets are removed.
The name is limited to 100 characters and is validated against the pattern
^[a-zA-Z0-9_-]+$. TaruviBase derives a URL-safe slug from the name, and requests
address a type by that slug.
Sensitivity levels
A secret type carries one sensitivity level. The level controls the storage field used for the value:
| Level | Stored in | Encryption |
|---|---|---|
public | Plaintext value field | None |
private | Encrypted value field | Encrypted database field |
sensitive | Encrypted value field | Encrypted database field |
TaruviBase picks the field from the type's sensitivity level: a
public value is read from and written to the plaintext field, while private
and sensitive values use the encrypted field. Security and
limits describes the read-access
behavior for each level.
Scope and resolution
A secret is scoped by its app value:
app = null— a site secret, shared across every app in the site.app = <slug>— an app secret, belonging to one app.
Resolution uses two tiers, with the app value taking precedence:
When a request supplies an app slug, an app secret with the requested key overrides a site secret with the same key. When a request supplies no app slug, only site secrets resolve. A batch or list request that supplies an app slug merges app and site secrets, and the app value wins for a shared key.
Keys are unique within their scope: a key is unique among site secrets, and a key is unique per app among app secrets. The same key can therefore exist once at the site level and once within each app.
Console selects scope from where you open Secrets; the create dialog has no separate scope field:
- The site Secrets tab creates and lists site secrets.
- App Operate → Secrets creates app secrets and lists app scope only, so inherited site entries are not shown on that page.
Choose the site or app location before selecting Create Secret.
Values
A value is a string or a JSON object. The value is validated against the secret type's JSON schema before it is stored. A stored value is returned parsed as JSON when it is valid JSON, and as a string otherwise.
Keys can be up to 255 characters. The API accepts any characters, but Console allows fewer.
Tags
A tag is a slug label applied to a secret. A secret can carry many tags, and tags organize and filter secrets in list requests. Tags are managed for the site and referenced by slug when a secret is created or updated.
Audit history
Every secret keeps a metadata change history. Each record captures who made the change, when, and which action occurred. The history endpoint resolves the live secret first, so it returns the create and update records for an existing secret; once a secret is deleted, its history is no longer retrievable through the endpoint.
The history excludes the secret value. Neither the plaintext field nor the encrypted field is recorded in history.
Keep in mind
- Never print secret values in logs.
- Store credentials as secrets, not as ordinary site settings.
- A deleted secret can't be recovered, so keep a copy of any value you may need.