Developer platform · API v1

Move encrypted secrets without exposing plaintext.

Use the CLI for day-to-day vault workflows or call the versioned JSON API directly for automation.

Install the CLI Explore the API

Base URL: https://groundedvault.com
API version: /api/v1
Authentication: Bearer gv_…

01 · Get started

Install and authenticate

Terminal OAuth device login

curl -fsSL https://groundedvault.com/install-cli | sh
grounded login --scope write --server https://groundedvault.com
grounded status

The installer requires curl and Erlang's escript. Interactive login opens a short-lived device authorization in your browser and stores the resulting token in your local Grounded configuration.

Choose read for listing and pulling secrets. Choose write only when you need to create, update, import, or rotate data.

02 · Common workflows

Use the CLI for encrypted operations

Import a .env file

grounded import billing-app

# Choose a file and existing environment
grounded import billing-app \
  --file .env.local \
  --environment staging

The complete file is validated before any writes. Values are encrypted locally and plaintext is never printed. A missing named vault is created with development; provision other environments first.

Pull and decrypt

# JSON output
grounded pull billing-app \
  --environment development

# .env-style output
grounded pull billing-app \
  --environment development \
  --format env

Pull retrieves the encrypted bundle and its authorized key versions, then decrypts locally. Avoid writing decrypted output to disk unless the destination is protected.

Manage a secret

grounded secrets create billing-app \
  "Stripe secret key" STRIPE_SECRET_KEY

grounded secrets set billing-app \
  STRIPE_SECRET_KEY \
  --environment development

Omitting --value prompts for the value. Use a vault name or numeric ID and a secret name, key, or numeric ID.

Use an API key in CI

export GROUNDED_URL=https://groundedvault.com
export GROUNDED_TOKEN=gv_your_api_key

grounded pull billing-app \
  --environment production \
  --format env

Create the narrowest practical API key in the web app. Tokens can be read-only or write-enabled, scoped to an account or selected vaults, IP-restricted, and expiring.

03 · Command reference

Available CLI commands

# Authentication
grounded login [--scope read|write] [--server URL]
grounded login --api-key TOKEN [--server URL]
grounded status
grounded logout

# Vaults and environments
grounded vaults list
grounded vaults create NAME
grounded environments list VAULT
grounded environments create VAULT NAME

# Secrets
grounded secrets list VAULT
grounded secrets show VAULT SECRET
grounded secrets create VAULT NAME KEY
grounded secrets update VAULT SECRET [--name NAME] [--description TEXT]
grounded secrets set VAULT SECRET --environment NAME [--value VALUE]

# Keys and bulk workflows
grounded keys get VAULT VERSION
grounded keys rotate VAULT
grounded import VAULT [--file PATH] [--environment NAME]
grounded pull VAULT [--environment NAME] [--format json|env]

# Escape hatch for versioned API calls
grounded request METHOD PATH [--data JSON]

Run grounded help to print this reference in the terminal. environments can be shortened to envs, and whoami is an alias for status.

04 · HTTP API

Call the API directly

Send an API key in the Authorization header. Every response is JSON, and authenticated requests are rate-limited and written to the access log.

cURL Authenticated request

curl \
  -H "Authorization: Bearer $GROUNDED_TOKEN" \
  "https://groundedvault.com/api/v1/vaults/42/bundle?environment=development"

Read operations

GET /api/v1/account Show the authenticated account.

GET /api/v1/vaults List vaults granted to the API key.

GET /api/v1/vaults/:vault_id/environments List a vault's environments.

GET /api/v1/vaults/:vault_id/secrets List secret metadata; optionally filter by environment.

GET /api/v1/vaults/:vault_id/secrets/:secret_id Return one encrypted secret version.

GET /api/v1/vaults/:vault_id/bundle Return an environment's encrypted secret bundle.

GET /api/v1/vaults/:vault_id/key_versions/:version Return one authorized vault key version.

Write operations

POST /api/v1/vaults Create a vault with its default development environment.

POST /api/v1/vaults/:vault_id/environments Provision an additional environment.

POST /api/v1/vaults/:vault_id/secrets Create secret metadata.

PATCH /api/v1/vaults/:vault_id/secrets/:secret_id Update a secret's name or description.

POST /api/v1/vaults/:vault_id/secrets/:secret_id/versions Store a client-encrypted value for an environment.

POST /api/v1/vaults/:vault_id/key_versions Rotate the vault key and re-encrypt stored secret versions.

Write request bodies

POST /api/v1/vaults
{"name":"billing-app","description":"Billing service secrets"}

POST /api/v1/vaults/:vault_id/environments
{"name":"staging","description":"Pre-production"}

POST /api/v1/vaults/:vault_id/secrets
{"name":"Stripe secret key","key":"STRIPE_SECRET_KEY"}

PATCH /api/v1/vaults/:vault_id/secrets/:secret_id
{"name":"Stripe API key","description":"Used by the billing worker"}

POST /api/v1/vaults/:vault_id/secrets/:secret_id/versions
{"environment_id":3,"vault_key_version":2,"encrypted_value":"gvenc1:…"}

05 · Encryption contract

Keep plaintext on the client

Encrypted values submitted to the API use gvenc1:<Base64Payload>. Decode the authorized vault key as unpadded Base64url, then encrypt with AES-256-GCM using a random 12-byte nonce. Concatenate nonce || ciphertext || 16-byte tag and encode the payload as standard Base64.

Bundle responses contain ciphertext and list the required key_versions. Fetch each key version separately. Bundle and key requests have independent authorization and audit events; the CLI implements this flow for you.