Configuration

Unkey services read configuration from a TOML file passed at startup. Environment variables can be referenced with ${VAR} and are expanded before parsing. Defaults and validation run after parsing.

Configuration model

The config schema maps to svc/vault/config.go. Vault loads configuration via config.Load, which expands ${VAR} environment variables before parsing. Minimal config example:

http_port = 8060
region = "${UNKEY_REGION}"
instance_id = "${POD_NAME}"
bearer_token = "${UNKEY_VAULT_TOKEN}"

[encryption]
master_key = "${UNKEY_ENCRYPTION_MASTER_KEY}"

[storage.s3]
url = "${UNKEY_S3_URL}"
bucket = "${UNKEY_S3_BUCKET}"
access_key_id = "${UNKEY_S3_ACCESS_KEY_ID}"
access_key_secret = "${UNKEY_S3_ACCESS_KEY_SECRET}"

string

Used for tracing attributes. Set to pod name in Kubernetes. Example: vault-7d9b8c4f5d-2kq7m.

int

default:"8060"

Port for HTTP and RPC traffic. Example: 8060.

string

Included in logs and traces. Example: us-east-1.

string

required

Used for RPC auth. Must be non-empty. Example: "s3cr3t-token".

Encryption

object

required

Encryption key configuration.

Show Fields

string

required

Base64-encoded KeyEncryptionKey protobuf. Used for new writes. Example: "CiV2YXVsdC1rZXktMSIsIk9TQjRvYjBqWnU9".

string

Optional base64 key used to decrypt existing data during rotation. Example: "CiV2YXVsdC1rZXktMCIsIk9TQjRvYjBqWnU9".

Vault expects master_key values to be a base64 encoding of the serialized KeyEncryptionKey protobuf. This format is produced by the vault key generation code. Example:

[encryption]
master_key = "${UNKEY_ENCRYPTION_MASTER_KEY}"
previous_master_key = "${UNKEY_ENCRYPTION_PREVIOUS_MASTER_KEY}"

Storage

Vault persists encrypted DEKs through one storage backend. Configure exactly one of [storage.s3] or [storage.disk]. Setting both, or neither, fails validation at startup.

S3 storage

S3-compatible object storage is the production backend.

object

S3-compatible storage configuration.

Show Fields

string

required

S3-compatible endpoint URL. Example: "https://s3.us-east-1.amazonaws.com".

string

required

Bucket name for encrypted objects. Example: "unkey-vault".

string

required

Access key ID for storage. Example: "AKIA...".

string

required

Access key secret for storage. Example: "wJalrXUtnFEMI/K7MDENG/bPxRfiCY".

Example:

[storage.s3]
url = "${UNKEY_S3_URL}"
bucket = "${UNKEY_S3_BUCKET}"
access_key_id = "${UNKEY_S3_ACCESS_KEY_ID}"
access_key_secret = "${UNKEY_S3_ACCESS_KEY_SECRET}"

Vault initializes the S3 client on startup and creates the bucket if it does not exist.

Disk storage

A local filesystem backend exists for local development so you do not need to run a minio container. Object keys are written as forward-slash relative paths under path, mirroring the S3 layout. Do not use this backend in production: it does not replicate, it has no durability beyond the host filesystem, and multiple vault replicas pointed at the same path will race.

object

Local filesystem storage configuration.

Show Fields

string

required

Directory where encrypted secrets are persisted. Created at startup if missing. Example: "./vault-data".

Example:

[storage.disk]
path = "./vault-data"

Observability

object

Tracing and logging configuration. Each nested section is optional.

Show Fields

float

default:"0.25"

Trace sampling rate from 0.0 to 1.0. Example: 0.1.

float

default:"1.0"

Log sampling rate for fast events. Example: 0.01.

duration

default:"1s"

Slow log threshold. Example: "2s".

Vault accepts observability.metrics in the config file, but the vault runtime does not start a Prometheus endpoint. Example:

[observability.tracing]
sample_rate = 0.1

[observability.logging]
sample_rate = 0.01
slow_threshold = "2s"

Environment variables

The Helm chart provides these variables for the default config template:

env

required

Bearer token for vault RPC auth. Example: "s3cr3t-token".

env

required

Base64-encoded master key. Example: "CiV2YXVsdC1rZXktMSIsIk9TQjRvYjBqWnU9".

env

Optional previous master key for rotation. Example: "CiV2YXVsdC1rZXktMCIsIk9TQjRvYjBqWnU9".

env

required

S3-compatible endpoint URL. Example: "https://s3.us-east-1.amazonaws.com".

env

required

Bucket name for encrypted objects. Example: "unkey-vault".

env

required

S3 access key ID. Example: "AKIA...".

env

required

S3 access key secret. Example: "wJalrXUtnFEMI/K7MDENG/bPxRfiCY".

env

Region label for observability. Example: "us-east-1".

env

OTEL exporter endpoint. Example: "http://otel-collector.monitoring.svc.cluster.local:4318".

env

OTEL exporter protocol. Example: "http/protobuf".

Authentication

Vault requires callers to pass an Authorization: Bearer <token> header. The token must match bearer_token from the config.

Key management and rotation

Master keys and bearer tokens are managed manually. When you rotate keys, generate a new master key and update AWS Secrets Manager. Keep the previous master key in UNKEY_ENCRYPTION_PREVIOUS_MASTER_KEY until all data is re-encrypted.

Generate a master key

From the repo root, use the Unkey CLI to generate a base64-encoded master key:

go run . dev generate-master-key

The command prints the encoded key to stdout. Store the value in AWS Secrets Manager as UNKEY_ENCRYPTION_MASTER_KEY.

Generate a bearer token

Vault accepts any non-empty bearer token. Use a strong random value and store it as UNKEY_VAULT_TOKEN:

openssl rand -base64 32

High-level flow:

Generate a new master key and set it as UNKEY_ENCRYPTION_MASTER_KEY.
Move the prior master key to UNKEY_ENCRYPTION_PREVIOUS_MASTER_KEY.
Update AWS Secrets Manager for unkey/vault.
Re-sync the Helm release to roll the vault pods.
Remove UNKEY_ENCRYPTION_PREVIOUS_MASTER_KEY after re-encryption is complete.

Vault does not expose a DEK re-encryption RPC. Re-encryption requires running the internal RollDeks flow, which walks stored DEKs and rewrites them with the current master key.

Secret sources

The default Helm chart uses External Secrets to source the vault secrets from unkey/vault in AWS Secrets Manager:

secret

required

Used for RPC authentication. Example: "s3cr3t-token".

secret

required

Base64-encoded master key. Example: "CiV2YXVsdC1rZXktMSIsIk9TQjRvYjBqWnU9".

secret

Optional key for rotation. Example: "CiV2YXVsdC1rZXktMCIsIk9TQjRvYjBqWnU9".

secret

required

S3 endpoint. Example: "https://s3.us-east-1.amazonaws.com".

secret

required

Bucket name. Example: "unkey-vault".

secret

required

Access key ID. Example: "AKIA...".

secret

required

Access key secret. Example: "wJalrXUtnFEMI/K7MDENG/bPxRfiCY".

Example configuration

http_port = 8060
region = "${UNKEY_REGION}"
instance_id = "${POD_NAME}"
bearer_token = "${UNKEY_VAULT_TOKEN}"

[encryption]
master_key = "${UNKEY_ENCRYPTION_MASTER_KEY}"
previous_master_key = "${UNKEY_ENCRYPTION_PREVIOUS_MASTER_KEY}"

[storage.s3]
url = "${UNKEY_S3_URL}"
bucket = "${UNKEY_S3_BUCKET}"
access_key_id = "${UNKEY_S3_ACCESS_KEY_ID}"
access_key_secret = "${UNKEY_S3_ACCESS_KEY_SECRET}"

[observability.tracing]
sample_rate = 0.1

[observability.logging]
sample_rate = 0.01
slow_threshold = "2s"

Overview

Overview

Services

RFCs

Configuration model

Encryption

Storage

S3 storage

Disk storage

Observability

Environment variables

Authentication

Key management and rotation

Generate a master key

Generate a bearer token

Secret sources

Example configuration

​Configuration model

​Encryption

​Storage

​S3 storage

​Disk storage

​Observability

​Environment variables

​Authentication

​Key management and rotation

​Generate a master key

​Generate a bearer token

​Secret sources

​Example configuration

​Related docs

Configuration model

Encryption

Storage

S3 storage

Disk storage

Observability

Environment variables

Authentication

Key management and rotation

Generate a master key

Generate a bearer token

Secret sources

Example configuration

Related docs