Vault

The Vault is Curlex's built-in secure credential store. It is the safest place to keep your most sensitive values — API keys for payment providers, OAuth client secrets, database passwords, private tokens — because secrets stored in the Vault are:

• Encrypted and stored in your operating system's keychain, not in Curlex's database.
• Never written to your collection files, so they cannot accidentally end up in a Git commit or an exported JSON file.
• Domain-restricted — each secret can be locked to specific API hostnames, so a Stripe secret cannot accidentally be sent to a different API even if you use the same variable name.
• Separate from environments — you can share or export an environment without leaking credentials, because the values never live in the environment at all.

Vault vs Environment Variables

Both Vault secrets and environment variables can be substituted into requests using {{...}} syntax. The difference is in where the values are stored and how safe they are.

Rule of thumb: If a credential would cause damage if it leaked — payment keys, production API tokens, OAuth client secrets — put it in the Vault. Use environment variables for things like base URLs, non-sensitive config, and test data.

Setting Up the Vault

The Vault requires a one-time setup the first time you use it. During setup, Curlex generates a Vault Key — a 64-character cryptographic key that encrypts and decrypts your secrets.

First-Time Setup

1. Click Vault in the status bar at the bottom of the window, or navigate to the Vault from the sidebar.
2. The Vault setup screen appears, showing your newly generated Vault Key.
3. Save this key somewhere safe before continuing. If you lose the key, your secrets cannot be recovered. Your options:
   • Click Copy to copy it to your clipboard, then paste it into a password manager.
   • Click Download to save it as curlex-vault-key.txt.
4. If you want Curlex to remember the key for you, check Save this key to my password manager. When this is checked, Curlex stores the key in your OS keychain alongside your secrets — you will be able to unlock the Vault with one click instead of typing the key each time. Most users should enable this.
5. Click Open Vault to complete setup. The Vault is now ready to use.

Why does Curlex ask you to save the key separately? The key is stored in your OS keychain when you check that option, but if you ever move to a new machine, reset the keychain, or uninstall Curlex, having a backup copy means you can re-import your secrets instead of losing them permanently.

Locking and Unlocking the Vault

The Vault starts in a locked state every time you launch Curlex. Locked means the secrets exist in the keychain but are not accessible to requests yet.

Unlocking

If you saved the key to your password manager during setup: The Vault screen shows an Open Vault button. Click it and Curlex retrieves the key from your keychain automatically — no typing required.

If you did not save the key to the password manager: Type or paste your Vault Key into the unlock field and click Unlock.

Once unlocked, the Vault stays open for the entire session. Secrets are available to all requests until you lock it or close the app.

Locking Manually

Click Lock Vault inside the Vault panel to lock it immediately. Any {{vault:name}} references in requests will stop resolving until you unlock again. This is useful when you step away from your computer and want to ensure secrets are not accessible.

Adding Secrets

With the Vault unlocked, click + Add Secret to create a new secret.

After saving, the secret appears in the list with its key name, masked value, allowed domains, and when it was last modified.

Using Vault Secrets in Requests

Reference a Vault secret in any request field using this syntax:

{{vault:your-secret-key}}

You can use this in:

• The URL: https://{{vault:api-base-url}}/endpoint
• A header value: Authorization: Bearer {{vault:production-token}}
• The request body: { "apiKey": "{{vault:stripe-live-key}}" }
• Query parameters: ?token={{vault:webhook-secret}}
• Auth fields: paste {{vault:oauth-client-secret}} into the Client Secret field of an OAuth 2.0 flow

When Curlex sends the request, it resolves the placeholder to the actual secret value from the keychain. The resolved value appears in the request that is sent, but it is never written anywhere in Curlex's own storage.

Domain Restrictions

If a secret has allowed domains configured, Curlex checks the request URL's hostname against those domains before resolving the secret:

• Exact match: api.stripe.com matches only api.stripe.com.
• Wildcard: *.example.com matches dev.example.com, api.example.com, etc., but not example.com itself.
• Multiple domains: Enter them comma-separated: api.stripe.com, hooks.stripe.com.
• Any domain: Leave the field blank to allow the secret to be used with any hostname.

If the request's domain does not match, the {{vault:name}} placeholder is left unresolved and Curlex shows an error. This is intentional — it prevents a secret configured for api.stripe.com from being accidentally sent to api.staging.myapp.com or any other host.

Managing Secrets

The unlocked Vault shows all your secrets in a table. From here you can:

Edit a secret: Click any row to edit its key, value, or allowed domains inline.

Toggle a secret on or off: Each secret has an enable/disable toggle. A disabled secret is never resolved in requests, even if the domain matches. Use this to temporarily deactivate a secret without deleting it.

Reveal a value: Click the eye icon on any row to temporarily show the secret value in plain text.

Delete a secret: Click the trash icon on a row to permanently delete it. This removes the secret from your keychain.

Search: Use the filter bar at the top to search secrets by name — useful when you have many secrets.

Exporting and Importing Secrets

You can export all your Vault secrets to a file for backup or for moving to another machine.

Exporting

1. In the unlocked Vault, click Export.
2. Curlex asks you to enter a passphrase. This passphrase is used to encrypt the export file — choose something strong and remember it.
3. A file is saved to your computer. The file is encrypted with AES-256-GCM using a key derived from your passphrase (PBKDF2, 100,000 iterations, SHA-256). Without the passphrase, the file cannot be decrypted.

The export file contains your secret values in encrypted form. Keep it as secure as you would any credential file.

Importing

1. In the unlocked Vault (on the same or a different machine), click Import.
2. Select the exported file.
3. Enter the passphrase you used when exporting.
4. Curlex decrypts and imports all secrets into the Vault.

Secrets from the import are added alongside existing secrets. If a secret with the same key already exists, it is updated.

Resetting the Vault

If you lose your Vault Key and no longer have access to the keychain that stored it, you can reset the Vault. This permanently deletes all stored secrets and cannot be undone.

To reset:

1. Open the Vault panel (locked or unlocked).
2. Click Reset Vault at the bottom.
3. Confirm the action in the dialog.

After resetting, you go through first-time setup again and start with an empty Vault.

Security Details

For users who want to understand the technical implementation:

Common Questions

What happens to vault secrets when I export a collection? They are never included. Collection exports only contain what is in the collection itself. {{vault:name}} references appear as literal placeholder text in the export — the values are not attached.

What about Git Sync — do secrets get committed? No. Vault secrets are stored in the OS keychain, completely outside of everything that Git Sync writes. Your .curlex/ repository files will never contain vault secret values.

Can I share vault secrets with a teammate? The most secure way is to export the vault (encrypted with a passphrase) and send the file and passphrase through separate secure channels — for example, the file over encrypted email and the passphrase over a secure messaging app. Your teammate imports the file into their own Vault on their machine.

What if I change the secret value on one machine but not another? Vault secrets are local to each machine's keychain. They are not synced automatically. If you change a production API key, you need to update it in the Vault on every machine where Curlex is installed.

Can I use a vault secret in an OAuth 2.0 Client Secret field? Yes. Paste {{vault:my-client-secret}} directly into the Client Secret field of an OAuth 2.0 flow configuration. Curlex resolves it before initiating the flow.

What if the Vault is locked when a request runs? If a request contains a {{vault:name}} reference and the Vault is locked, the placeholder is not resolved — the literal text {{vault:name}} is sent instead. Open and unlock the Vault before sending any requests that use vault secrets.