Penv Cloud API
The HTTP API a pipeline, a sync tool or a script calls to read and write the values in one project and environment.
Penv Cloud holds the keys and settings your apps need, and this API is how a machine reads them. Every route answers JSON, and a read hands the plaintext value over TLS to the scoped identity that asked for it.
Who calls it
A CI platform reading values into a build. A pull-based tool that fetches a whole environment on a
timer, such as External Secrets Operator's webhook provider. A script on a server that wants one
value. Your application code usually calls none of this, because penv run and penv pull do it
for you.
Base URL
https://penv.cloudOne call looks like this.
curl https://penv.cloud/api/v1/secrets/DATABASE_URL \
-H "Authorization: Bearer pck_..."{ "value": "postgres://example/not-a-real-secret", "version": 3 }The credential decides the workspace, the project and the environment before you call. There is no
workspace or environment in the path, and an address that scope does not hold answers 404 with
not_found. Authentication is where a credential comes from.
The four groups
| Group | What it covers |
|---|---|
| Secrets | List names, read one value, write one, delete one, and read a whole environment in a single call. |
| Dynamic | Mint one short-lived credential from an engine you connected, returned once and stored nowhere. |
| Auth | Trade a proof the host already has for a pck_ credential, and revoke one when the job ends. |
| Discovery | The two public documents another cloud reads to trust tokens Penv Cloud mints. Unauthenticated. |
What is not here
The console, the command line and our own background jobs call further endpoints under /api/v1:
workspaces, projects, environments, reveal approvals, billing webhooks, scheduled jobs, and the SCIM
endpoint your directory writes to. None of those are a public contract. They change whenever the
console changes, with no notice and no version bump. The operations on these pages are the ones we
keep stable, and versioning says what stable means.
Every error body is the same shape, {"error": "snake_case_code"}. A 429 from one of our own
ceilings carries a retry-after header. Error codes lists every code the
API can answer with.
Next: authentication.