Secret Providers

Secret providers are connections to external secrets managers. You configure a provider connection once with the necessary credentials, then reference it when creating secrets that should be fetched from that provider at runtime.

Supported providers

All cloud SDKs are declared as optional dependencies in the Provenance API. They're installed with npm install but won't break the server if unavailable on a specific platform.

Creating a provider connection

Via the UI

Navigate to Settings → Secret Providers and click + New Connection.

1. Enter a connection name (e.g. "Production AWS", "Staging Vault")
2. Select the provider type
3. Fill in the provider-specific configuration fields
4. Optionally add a description
5. Click Create

Sensitive fields (access keys, tokens, client secrets) are encrypted before storage using the same AES-256-GCM encryption as Provenance-stored secrets.

Via the API

POST /api/secret-providers
{
  "name": "Production AWS",
  "type": "aws-sm",
  "config": {
    "region": "eu-west-1",
    "accessKeyId": "AKIA...",
    "secretAccessKey": "..."
  },
  "description": "Production AWS account"
}

Provider configuration

AWS Secrets Manager

Secret path format: The secret name or ARN in AWS Secrets Manager.

my-app/api-keys          → fetches the full secret string
arn:aws:secretsmanager:eu-west-1:123456:secret:my-secret

If the secret value is JSON and you need a specific key, configure jsonKey in the per-secret provider config:

POST /api/secrets
{
  "secretPath": "stripe.apiKey",
  "provider": "aws-sm",
  "providerPath": "prod/stripe",
  "secretProviderId": "...",
  "providerConfig": { "jsonKey": "api_key" }
}

Azure Key Vault

Secret path format: The secret name in Key Vault (not the full URL).

my-api-key
database-password

GCP Secret Manager

Secret path format: Either the short name or the full resource path.

my-secret                                              → auto-expands to projects/{projectId}/secrets/my-secret/versions/latest
projects/my-project/secrets/my-secret/versions/latest  → used as-is
projects/my-project/secrets/my-secret/versions/3       → specific version

HashiCorp Vault

Secret path format: The Vault KV path. For KV v2, the /data/ segment is auto-inserted if missing.

secret/data/my-app/api-key    → used as-is (KV v2 explicit)
secret/my-app/api-key          → auto-converted to secret/data/my-app/api-key

If the secret contains multiple keys, use jsonKey to extract a specific one:

POST /api/secrets
{
  "secretPath": "db.password",
  "provider": "vault",
  "providerPath": "secret/data/database",
  "secretProviderId": "...",
  "providerConfig": { "jsonKey": "password" }
}

If jsonKey is not set and the secret has a single key, that value is returned. If it has multiple keys, the full JSON is returned as a string.

Editing connections

When editing a provider connection, sensitive fields show ••••••••. Leaving them as-is preserves the existing encrypted value. Clear the field and enter a new value to update it.

Deleting connections

A provider connection cannot be deleted if any secrets reference it. Delete or reassign the referencing secrets first. The API returns a 409 Conflict with the count of referencing secrets.

Provider types API

The GET /api/secret-providers/types endpoint returns the available provider types with their configuration schemas. This powers the dynamic form in the UI.

GET /api/secret-providers/types

[
  {
    "type": "aws-sm",
    "name": "AWS Secrets Manager",
    "description": "Fetch secrets from AWS Secrets Manager at runtime",
    "configSchema": [
      { "key": "region", "label": "Region", "type": "text", "required": true },
      { "key": "accessKeyId", "label": "Access Key ID", "type": "password", "required": false, "sensitive": true },
      { "key": "secretAccessKey", "label": "Secret Access Key", "type": "password", "required": false, "sensitive": true }
    ]
  }
]

Self-hosted setup

For self-hosted deployments, ensure:

1. Master key: Set SECRETS_MASTER_KEY in your .env file. This key encrypts both Provenance-stored secrets and provider connection credentials. Use a strong random string and back it up — losing it means losing access to all encrypted secrets.

2. Cloud SDKs: The relevant cloud SDK must be installed for each provider you want to use. They're declared as optional dependencies and installed with npm install:

   • AWS: @aws-sdk/client-secrets-manager
   • Azure: @azure/keyvault-secrets + @azure/identity
   • GCP: @google-cloud/secret-manager
   • Vault: No SDK needed (uses HTTP API via fetch)

3. IAM / default credentials: If you omit explicit credentials in the provider config, the SDK falls back to the environment's default credential chain (IAM roles, managed identity, application default credentials). This is the recommended approach for cloud-hosted deployments.