Secrets Storage

Secrets Storage keeps values such as test credentials in named stores within a namespace. You can use a local encrypted store or read values from a supported external secret service. In a mock response or template, $.secrets.<store>.<key> refers to an entry without copying its value into the mock definition.

Table of Contents

1. Why centralised secrets?
2. Stores and entries
3. Permissions
4. Referencing secrets in mocks
5. Vault integration
6. SDK and CLI examples

Why centralised secrets?

Keep credentials out of mock definitions so you can change a value without editing every mock that uses it. A store list shows names and entry metadata, while reading a local entry’s value requires secret:read. To rotate a local entry, supply its new value; Mockarty replaces the old value and increases the entry version.

For local (inline) stores with the default software key setup, an administrator must configure MOCKARTY_PII_ENCRYPTION_KEY before starting Mockarty. Without an encryption key, creating or reading local entries fails. See Admin Setup for the environment variable.

Stores and entries

A secret store is a named container inside a namespace. An inline store holds entries with a key and an encrypted value. External backends read values from their respective services; manage those values in the external service.

Stores have a backend field:

• inline — default; Mockarty stores encrypted entry values locally.
• vault — reads values from HashiCorp Vault KV v1 or v2.
• aws_sm — reads from AWS Secrets Manager; configure a region and AWS credentials.
• gcp_sm — reads from Google Secret Manager; configure a project and Google credentials.
• azure_kv — reads from Azure Key Vault; configure its URL and Azure credentials.
• custom_api — reads from a configured HTTPS endpoint; supports request headers and an optional JSONPath extractor.

For external backends, configure the connection in Stores → Secrets and create or rotate values in the external service. The entry create/rotate examples below apply to inline stores.

The Stores → Secrets list and its entries dialog show separate loading, empty, sign-in, access-denied, and temporary-unavailability states. If a read fails, use Retry after resolving the cause; the page does not display a raw HTTP error in place of the entries.

Switching a store off

A store is enabled by default. When you disable it, Mockarty stops resolving
its values. The entry API also refuses writes and rotations with 409 and
names the disabled store. A mock that refers to a disabled value cannot
substitute that value.

Existing entry names remain visible in the list. Re-enable the store to use
its values again; disabling it does not delete them.

Permissions

Tokens without secret:read receive 403 when attempting GET /api/v1/stores/secrets/:id/entries/:key.

When configuring a Vault token or custom API authentication secret on the
Stores → Secrets tab, select Select secret entry beside the secret ID
field. The picker searches entries in enabled inline stores in the current
namespace and shows only the store name and entry key. It never displays or
returns the secret value. The picker requires secret:read; you can still
enter an entry ID manually when the picker is unavailable. Changing namespace
closes the editor and clears its current selection.

Referencing secrets in mocks

Inside a mock response body, template, or test plan variable, write:

Bearer $.secrets.payments.stripe_api_key

Mockarty looks up payments in the current namespace and substitutes the current value of stripe_api_key. If the store or key cannot be read, Mockarty cannot substitute that value; it does not insert an old or unrelated value. A resolved value appears in the mock response sent to its caller, so use this only where that caller is meant to receive it.

Vault integration

For a first-time Vault connection, save a Vault token as an entry in an enabled inline store in the same namespace. Copy that entry’s id from the creation response. Then call PUT /api/v1/namespaces/{ns}/integrations/vault with the Vault URL and tokenSecretId. This creates a Vault-backed store named vault-default.

curl -sS -X PUT http://localhost:5770/api/v1/namespaces/production/integrations/vault \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://vault.example.com","tokenSecretId":"<inline-entry-id>","mount":"secret","kvVersion":2}'

With the CLI, use the same stored entry ID:

mockarty-cli namespace vault-integrate --ns production \
  --url https://vault.example.com --token-secret-id "$VAULT_TOKEN_ENTRY_ID" \
  --mount secret

The token entry must already exist in production; secret:write is required for this request. To change an existing vault-default store, use the store editor instead of repeating this creation call.

SDK and CLI examples

These examples use an inline store in sandbox. Create an API token with secret:write; add secret:read if you need to fetch values. Replace the example values with your own and use the store id returned by the create call as STORE_ID.

cURL

# Create a store
curl -sS -X POST http://localhost:5770/api/v1/stores/secrets \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"payments","namespace":"sandbox","backend":"inline"}'

# Add an entry
curl -sS -X POST http://localhost:5770/api/v1/stores/secrets/$STORE_ID/entries \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"stripe_api_key","value":"example-old-value"}'

# Rotate
curl -sS -X POST http://localhost:5770/api/v1/stores/secrets/$STORE_ID/entries/stripe_api_key/rotate \
  -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"example-new-value"}'

CLI

mockarty-cli secrets store create --name payments --backend inline
mockarty-cli secrets entry create --store "$STORE_ID" --key stripe_api_key --value example-old-value
mockarty-cli secrets entry rotate --store "$STORE_ID" --key stripe_api_key --value example-new-value
mockarty-cli secrets entry list   --store "$STORE_ID"

Go

store, err := client.Secrets().CreateStore(ctx, mockarty.SecretStore{Name: "payments", Backend: "inline"})
if err != nil { panic(err) }
_, err = client.Secrets().CreateEntry(ctx, store.ID, mockarty.SecretEntry{
    Key:   "stripe_api_key",
    Value: "example-old-value",
})
if err != nil { panic(err) }
_, err = client.Secrets().RotateEntry(ctx, store.ID, "stripe_api_key", "example-new-value")
if err != nil { panic(err) }

Python

store = client.secrets.create_store(name="payments", backend="inline")
client.secrets.create_entry(store["id"], key="stripe_api_key", value="example-old-value")
client.secrets.rotate_entry(store["id"], "stripe_api_key", "example-new-value")

Java

Map<String, Object> store = client.secrets().createStore("payments", null, "inline");
client.secrets().createEntry((String) store.get("id"), "stripe_api_key", "example-old-value", null);
client.secrets().rotateEntry((String) store.get("id"), "stripe_api_key", "example-new-value");

See also: JsonPath Guide, Admin Setup, Prompts Storage.