Secret Management

Overview

By default, Vikat stores provider API keys, virtual key values, and other credentials in its config database. Secret Management lets you keep those values in your own secret manager - Vikat stores a reference and resolves the real value at runtime. Once connected, any secret field in Vikat (provider keys, virtual key values, MCP auth headers, etc.) accepts a vault.<path> reference alongside the existing env.<VAR> and plaintext options.

Secret Management is an Enterprise-only feature and requires a PostgreSQL config store.

Access modes

Set access_mode to control how much Vikat interacts with your vault:

Mode	What Vikat does
`read_only` (default)	Resolves `vault.<path>` references. Never writes to or deletes from the backend.
`read_and_write`	Also auto-stores plaintext values you save via the dashboard or API, and deletes owned secrets when you remove an entity.

Start with read_only if you want to manage secrets yourself. Use read_and_write if you want Vikat to handle it - useful when migrating existing plaintext keys, since Vikat pushes the value to the vault on the next save.

Setup

Pick your backend and add a vault_store block inside your existing config_store in config.json.

AWS Secrets Manager
GCP Secret Manager
HashiCorp Vault

IAM role (recommended)
Static credentials
Role assumption

Attach an IAM role to your EC2 instance, ECS task, or EKS pod. No credentials needed in config - the SDK inherits the role automatically. For EKS with IRSA, annotate your service account with the role ARN and leave credentials unset.

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "aws-secrets-manager",
      "prefix": "vikat",
      "access_mode": "read_only",
      "aws": {
        "region": "us-east-1"
      }
    }
  }
}

Use static credentials when IAM roles are not available. access_key_id and secret_access_key must always be set together.

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "aws-secrets-manager",
      "prefix": "vikat",
      "access_mode": "read_only",
      "aws": {
        "region": "us-east-1",
        "access_key_id": "env.AWS_ACCESS_KEY_ID",
        "secret_access_key": "env.AWS_SECRET_ACCESS_KEY"
      }
    }
  }
}

Assume a cross-account or restricted IAM role on top of any existing credential source (instance profile, static credentials, or IRSA).

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "aws-secrets-manager",
      "prefix": "vikat",
      "access_mode": "read_only",
      "aws": {
        "region": "us-east-1",
        "role_arn": "arn:aws:iam::123456789012:role/VikatSecretsReader"
      }
    }
  }
}

AWS fields

Field	Required	Description
`region`	No	AWS region (e.g. `us-east-1`). Falls back to `AWS_DEFAULT_REGION` or instance metadata if unset.
`access_key_id`	No	Required when not using IAM roles. Must be set with `secret_access_key`.
`secret_access_key`	No	Must be set with `access_key_id`.
`session_token`	No	For STS-issued temporary credentials.
`role_arn`	No	IAM role to assume via STS.
`kms_key_id`	No	KMS key for encrypting new secrets (`read_and_write` only).

Minimum IAM policy for read_only:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-east-1:*:secret:vikat/*"
    },
    {
      "Effect": "Allow",
      "Action": "secretsmanager:ListSecrets",
      "Resource": "*"
    }
  ]
}

Add secretsmanager:CreateSecret, secretsmanager:PutSecretValue, and secretsmanager:DeleteSecret for read_and_write.

Workload Identity (recommended)
Service account key

Bind a GCP service account to your GKE workload or attach one to your Compute Engine instance. No credentials file needed.

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "gcp-secret-manager",
      "prefix": "vikat",
      "access_mode": "read_only",
      "gcp": {
        "project_id": "my-gcp-project"
      }
    }
  }
}

Pass the service account key as a JSON string (the full key file contents) or a path to a credentials file on disk. Using an environment variable is recommended.

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "gcp-secret-manager",
      "prefix": "vikat",
      "access_mode": "read_only",
      "gcp": {
        "project_id": "my-gcp-project",
        "credentials_json": "env.GCP_CREDENTIALS_JSON"
      }
    }
  }
}

GCP fields

Field	Required	Description
`project_id`	Yes	GCP project containing your secrets.
`credentials_json`	No	Service account key JSON string or file path. If omitted, Application Default Credentials are used.

Required IAM role: roles/secretmanager.secretAccessor for read_only. For read_and_write, also grant roles/secretmanager.secretCreator, roles/secretmanager.secretVersionAdder, and roles/secretmanager.secretDeleter.

Vikat uses the KV v2 secrets engine. Auth is resolved in order: explicit token → AppRole → ambient VAULT_TOKEN env var.

Token
AppRole
Ambient token

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "hashicorp-vault",
      "prefix": "vikat",
      "access_mode": "read_only",
      "hashicorp": {
        "address": "https://vault.internal:8200",
        "token": "env.VAULT_TOKEN"
      }
    }
  }
}

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "hashicorp-vault",
      "prefix": "vikat",
      "access_mode": "read_only",
      "hashicorp": {
        "address": "https://vault.internal:8200",
        "role_id": "env.VAULT_ROLE_ID",
        "secret_id": "env.VAULT_SECRET_ID",
        "mount_path": "secret"
      }
    }
  }
}

If VAULT_TOKEN is set in the environment and no token or AppRole is configured, Vikat inherits it automatically. Useful with Vault Agent injection.

{
  "config_store": {
    ...
    "vault_store": {
      "enabled": true,
      "type": "hashicorp-vault",
      "prefix": "vikat",
      "access_mode": "read_only",
      "hashicorp": {
        "address": "https://vault.internal:8200"
      }
    }
  }
}

HashiCorp fields

Field	Required	Description
`address`	No	Vault server URL. Reads `VAULT_ADDR` env var if unset.
`token`	No	Vault token.
`namespace`	No	Vault namespace (HCP Vault / Vault Enterprise).
`mount_path`	No	KV v2 mount path. Defaults to `secret`.
`role_id`	No	AppRole role ID. Must be set together with `secret_id`.
`secret_id`	No	AppRole secret ID. Must be set together with `role_id`.

Minimum Vault policy for read_only:

path "secret/data/vikat/*" {
  capabilities = ["read"]
}
path "secret/metadata/vikat/*" {
  capabilities = ["list"]
}

Add create, update, and delete on both paths for read_and_write.

Using vault references

Any secret field in Vikat that supports env.<VAR> also supports vault.<path>. This covers provider keys, virtual key values, MCP auth headers, plugin credentials, observability tokens, and more. Type the reference directly in the dashboard or set it in config.json.

Provider key field showing vault reference badge

For example, a provider key in config.json:

{
  "providers": {
    "openai": {
      "keys": [
        {
          "models": ["gpt-4o", "gpt-4o-mini"],
          "value": "vault.vikat/providers/openai/key"
        }
      ]
    }
  }
}

Fragment references

If your secret manager holds a JSON object with multiple keys, use vault.<path>#<key> to extract a single field. For example, if prod/shared-keys contains:

{
  "openai_api_key": "sk-...",
  "anthropic_api_key": "sk-ant-..."
}

You can reference each key independently:

vault.prod/shared-keys#openai_api_key
vault.prod/shared-keys#anthropic_api_key

Both resolve to their respective values with a single backend fetch for the shared secret.

Fragment references are never auto-deleted by Vikat in read_and_write mode, because the secret is externally managed and may be shared with other services.

Rotating secrets

Update the value in your secret manager, then restart the gateway to pick it up. vault.* references are resolved once, at boot, through the vault resolve hook (framework/secretstore) — the resolved value is then held in memory for the life of the process. This build has no background refresh loop and no cache-flush endpoint, so a rotated secret does not reach a running gateway on its own.

Earlier revisions of this page described an hourly background refresh and a POST /api/vault/flush-cache endpoint that broadcast across a cluster. Neither exists in this build — the endpoint is not registered on any route and would return 404. Roll your replicas after a rotation instead; they are stateless, so a rolling restart behind your load balancer costs no downtime.

Troubleshooting

Vikat fails to start with “vault: ping failed” The backend is unreachable or credentials are invalid. Check network connectivity, verify the IAM role / token has read permissions on the configured prefix, and confirm the region / address / project ID are correct. Secret field is empty after save The reference was saved but the backend returned nothing. Verify the secret exists at that exact path and the credentials have GetSecretValue / secretAccessor / read permission on it. New values aren’t being pushed to the vault access_mode must be read_and_write. The default read_only mode never writes to the backend. Old value still in use after rotation Flush the cache via POST /api/vault/flush-cache. If the issue persists, confirm the new version is active in the backend and not still pending. “vault: not enabled” from the flush-cache endpoint vault_store.enabled is false or the block is missing from config.json. Fix the config and restart.

Next steps

Audit Logs - use vault-backed keys for HMAC audit log signing
Clustering - cache flushes broadcast to all cluster peers automatically
AWS deployment guide - set up IRSA for keyless Secrets Manager access
GCP deployment guide - set up Workload Identity for keyless Secret Manager access

Getting Started

Moving from OSS

Release Cadence

Migration Guides

Features

Security

Secret Management

Overview

Access modes

Setup

AWS fields

GCP fields

HashiCorp fields

Using vault references

Fragment references

Rotating secrets

Troubleshooting

Next steps

​Overview

​Access modes

​Setup

​AWS fields

​GCP fields

​HashiCorp fields

​Using vault references

​Fragment references

​Rotating secrets

​Troubleshooting

​Next steps

Overview

Access modes

Setup

AWS fields

GCP fields

HashiCorp fields

Using vault references

Fragment references

Rotating secrets

Troubleshooting

Next steps