Authentication

Authorization: Bearer pck_...

Every call you make carries this header. Your host proves its identity once through an exchange, and we answer with a short-lived credential scoped to one environment (machine identity).

Principals

Exchange a CI platform token

T="$ACTIONS_ID_TOKEN" jq -n '{token:env.T}' | curl -X POST https://penv.cloud/api/v1/auth/oidc \
  -H "content-type: application/json" --data-binary @-

{ "credential": "pck_...", "expiresAt": "2026-09-17T12:15:00.000Z" }

jq puts the token in the body and curl reads it on stdin, so it stays out of the process list.

The token's audience must be your workspace id, so we refuse a token minted for another workspace. A slug is not accepted as the audience: a workspace name is not unique, so only the id names one workspace. The exchange is unauthenticated; the token is the proof. Per-platform token setup: connect.

Exchange for a delivery credential

T="$ACTIONS_ID_TOKEN" jq -n '{token:env.T}' | curl -X POST https://penv.cloud/api/v1/auth/oidc/delivery \
  -H "content-type: application/json" --data-binary @-

Same body; we bind the credential to one GitHub Actions run for five minutes. It records the repository, workflow, run id and attempt, so your audit row names one execution. We answer a pull_request_target run 403 refused, because that trigger runs untrusted pull request code with base-repository permissions (CI builds).

Exchange an AWS role

POST /api/v1/auth/aws takes an sts:GetCallerIdentity request you have already signed with your workload's instance, task or function role (AWS STS). We replay it to AWS to learn the signer. The signature is valid for that one call, so no secret leaves your machine.

{
  "method": "POST",
  "url": "https://sts.us-east-1.amazonaws.com/",
  "body": "Action=GetCallerIdentity&Version=2011-06-15",
  "headers": {
    "authorization": "AWS4-HMAC-SHA256 Credential=...,SignedHeaders=...,Signature=...",
    "x-amz-date": "20260917T120000Z",
    "x-penv-cloud-org": "4f1c1e6a-7c2e-4c1a-9b6e-2f0d1a8c3b55"
  }
}

curl -X POST https://penv.cloud/api/v1/auth/aws \
  -H "content-type: application/json" \
  --data-binary @signed-request.json

Exchange a signed challenge

For a host with no signed metadata and no secure element, such as a plain VPS. Your host holds an Ed25519 private key, we hold the public half, and a counter both sides remember advances on every login. The CLI runs these steps in the machine enroll command.

curl -X POST https://penv.cloud/api/v1/auth/keypair/enroll \
  -H "content-type: application/json" \
  -d '{"secret":"pce_...","publicKey":"MCowBQYDK2VwAyEA..."}'

{ "credentialId": "0f3c1a2b-...", "generation": 1 }

curl -X POST https://penv.cloud/api/v1/auth/keypair/challenge \
  -H "content-type: application/json" \
  -d '{"credentialId":"0f3c1a2b-..."}'

{ "nonce": "..." }

penv-cloud:keypair:v1
0f3c1a2b-...
<nonce>
1

curl -X POST https://penv.cloud/api/v1/auth/keypair \
  -H "content-type: application/json" \
  -d '{"credentialId":"0f3c1a2b-...","nonce":"...","generation":1,"signature":"..."}'

{ "credential": "pck_...", "expiresAt": "2026-09-17T12:15:00.000Z", "generation": 2 }

Lifetimes

Every exchange that mints a pck_ takes an optional ttlSeconds, a whole number of seconds, at least 60. We mint the shorter of it and the lifetime above; a longer ask is capped, not refused. Ask for less when an agent drives the session. Leave it out for the full lifetime. A value that is not a whole number answers 400 ttl_must_be_an_integer, and one under 60 answers 400 ttl_too_short.

We cap every expiry at the trust's own expiry, so a credential never outlives its rule. Read expiresAt rather than counting minutes.

Permissions

We resolve your credential in one indexed lookup to a workspace, project, environment, the identity's roles and the plan the rate limit reads. The scope is fixed when you create the identity; no request can widen it.

Listing names and opening values are separate grants, so you can make a list-only identity.

PENV_TOKEN

PENV_TOKEN=pck_... penv run -- pnpm build

penv reads a pck_ from PENV_TOKEN before the OS keychain. penv run passes it to the child, so set it on the step that needs it (environment variables, CI builds). The published GitHub Action reads no PENV_TOKEN: it mints and revokes a delivery credential per run.

Revoke a credential

curl -X POST https://penv.cloud/api/v1/auth/revoke \
  -H "Authorization: Bearer pck_..."

{ "revoked": true }

We revoke only the credential in the header, looked up by the hash of its secret. You need no permission, since you could discard the secret anyway. Idempotent: an already-revoked credential answers 200.

Call it at the end of your job and ignore a failure; the short lifetime bounds the credential, and revocation only shortens the window.

Next: rate limits.