Pull API

Fetch a project's secrets for one environment over HTTP with a read-only pull token. Server-side projects return plaintext; end-to-end-encrypted projects return ciphertext you decrypt locally.

Pull API#

The pull endpoint returns a project's secrets for a single environment. The hepgg-secrets package wraps it, but any HTTP client can call it.

Authentication#

Send a pull token as a bearer token (or, less preferably, as a ?token= query param). A token is either project-wide (reads any environment, pick one with ?env=) or environment-scoped (locked to one environment, ?env= is ignored).

Authorization: Bearer hsk_...

GET /api/v1/secrets/pull?token=hsk_...

Fetch secrets#

Server-side projects#

For a standard (server-side encrypted) project, Hep.gg decrypts and returns plaintext:

{
  "ok": true,
  "data": {
    "env": "production",
    "e2ee": false,
    "secrets": { "DATABASE_URL": "...", "API_KEY": "..." }
  }
}

End-to-end encrypted projects#

For an E2EE project, Hep.gg stores only ciphertext and returns it plus the key-derivation metadata. The client decrypts locally with the project passphrase or recovery key, which is 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>" }
  }
}

Errors#

Example#

curl -H "Authorization: Bearer hsk_..." \
     "https://hep.gg/api/v1/secrets/pull?env=production"

const res = await fetch(
  "https://hep.gg/api/v1/secrets/pull?env=production",
  { headers: { Authorization: "Bearer hsk_..." } },
);
const { data } = await res.json();
console.log(data.secrets.DATABASE_URL);