---
title: Hep.gg Secrets (LLM)
description: A developer secrets vault organized as Project -> Environment -> Secret, pulled into your app at launch over a token-authed API.
---

# Hep.gg Secrets

A developer secrets vault: organize secrets as Project -> Environment -> Secret
and pull an environment into your app at launch. The recommended client is the
hepgg-secrets npm package; the raw pull endpoint below works from any HTTP client.

Closed beta: applying is currently limited to tester accounts. Once approved,
create projects, environments, secrets, and read-only pull tokens in the
dashboard at /dashboard/secrets.

Base URL: https://hep.gg
Pull auth: Authorization: Bearer hsk_<...>   (or ?token=hsk_...)
  Tokens are read-only and created per project in the dashboard. A token is
  either project-wide (reads any environment via ?env=) or locked to one
  environment.

## Pull endpoint

### GET /api/v1/secrets/pull?env=<environment>&keys=<A,B>
Fetch a project's secrets for one environment.
  env    string   environment slug/name. Required for a project-wide token;
                  ignored for an environment-scoped token.
  keys   string   optional. Comma-separated names to return a subset; default is
                  the whole environment.

Server-side (default) projects - the API decrypts and returns plaintext:
  { "ok": true, "data": {
      "env": "production",
      "e2ee": false,
      "secrets": { "DATABASE_URL": "...", "API_KEY": "..." }
  } }

End-to-end-encrypted projects - the server stores only ciphertext and returns it
plus key-derivation metadata; the client decrypts locally with the project
passphrase / recovery key (never sent to Hep.gg):
  { "ok": true, "data": {
      "env": "production",
      "e2ee": true,
      "e2eeMeta": { "iterations": 210000, "saltPass": "...", "wrappedDekPass": "...",
                    "saltRec": "...", "wrappedDekRec": "...", "verifier": "..." },
      "secrets": { "DATABASE_URL": "<base64 ciphertext>", ... }
  } }
  Scheme: PBKDF2-SHA256(secret, salt, iterations) derives an AES-256-GCM key that
  unwraps a per-project data key (DEK); values are AES-256-GCM under the DEK
  (base64 iv||ciphertext+tag). The hepgg-secrets package implements this.

Errors:
  401 NO_TOKEN / BAD_TOKEN   missing, invalid, disabled, or suspended token.
  400                        a project-wide token called without ?env=.
  404                        unknown environment.
  429 RATE_LIMITED           per-token/IP rate limit; honor Retry-After (seconds).

## Recommended client: hepgg-secrets

  npm install hepgg-secrets --registry https://npm.hep.gg

  import { config } from "hepgg-secrets";
  await config({ env: "production", token: process.env.HEPGG_SECRETS_TOKEN });
  // for an E2EE project also pass key: <passphrase or recovery key>
  // your secrets are now in process.env

Inject-at-launch (like dotenv); it falls back to an encrypted last-good cache if
the network is briefly unavailable. Env-var fallbacks for every option:
HEPGG_SECRETS_URL / HEPGG_SECRETS_ENV / HEPGG_SECRETS_TOKEN / HEPGG_SECRETS_KEY.

## Limits
Free: 15 projects, 2 environments per project. Hep.gg Prime: 100 projects, 5
environments per project. ~64 KB max per value; unlimited secrets per
environment. A project's encryption mode (server-side or E2EE) is chosen at
creation and is immutable.

## Hep.gg dashboard (cookie auth - not for programmatic use)
  GET    /api/v1/secrets/projects
  POST   /api/v1/secrets/projects                 { name, e2ee?, e2eeMeta? }
  PATCH  /api/v1/secrets/projects/:id             { name }
  DELETE /api/v1/secrets/projects/:id
  GET    /api/v1/secrets/projects/:id/environments
  POST   /api/v1/secrets/projects/:id/environments
  GET    /api/v1/secrets/projects/:id/secrets     (the name x environment matrix)
  PUT    /api/v1/secrets/projects/:id/secrets/cell
  POST   /api/v1/secrets/projects/:id/secrets/bulk    (import)
  POST   /api/v1/secrets/projects/:id/secrets/copy    (copy one env into another)
  GET    /api/v1/secrets/projects/:id/tokens
  POST   /api/v1/secrets/projects/:id/tokens      -> returns the hsk_ token once
  GET    /api/v1/secrets/projects/:id/audit