Quick start: the one safe path

Hand one value to one named recipient, once, without the value ever entering your context or a transcript. Live in beta: production is https://ckrets.ai (a test origin you were given works the same way).

#1. The recipient gives you its key id

A key id looks like key_…; it is safe to share. The key itself (ck_live_…) never leaves the recipient. A recipient with no key mints one with POST /v1/keys (no account needed); see For agents.

#2. Create, naming that key

# quick-start: first-path
CKRETS=${CKRETS:-https://ckrets.ai}
IDEM=$(uuidgen)          # one per create; on a retry send the same one and get the first answer
jq -n --rawfile v ./db-password.txt '{"value":$v,"ttl":"1h","audience":{"type":"key","id":"key_7TQM4C…"},"purpose":"staging db password"}' |
  curl -sS --fail-with-body -X POST "$CKRETS/v1/secrets" -H 'content-type: application/json' \
    -H "idempotency-key: $IDEM" --data-binary @- > created.json
jq -er .token created.json      # hand this token to the recipient; keep created.json (its manageToken revokes)

jq --rawfile reads the value from the file, so it is never on a command line. No key is needed to send.

#3. The recipient reveals into the program that uses it

TOKEN=ck_…               # the token from step 2
npx -y @ckrets/helper@0.9.0 reveal "$TOKEN" --env DATABASE_URL -- ./deploy.sh

With CKRETS_KEY in its environment, the helper reads the free GET /v1/secrets/<token>/public view first (check its sender), proves the audience, reveals once, and starts ./deploy.sh with the value only in its environment. If the reveal fails, deploy.sh does not run. Without the helper, keep that property: assign first, then run.

v=$(curl -sS --fail-with-body -H "authorization: Bearer $CKRETS_KEY" "$CKRETS/v1/secrets/$TOKEN" | jq -er .value) &&
  DATABASE_URL="$v" ./deploy.sh

Never GET /v1/secrets/<token> to test a token: that is the reveal. /public is the safe check.

#Next

• Errors are application/problem+json: branch on type (Limits).
• CI jobs, servers (no-view) and people: the other quick-starts in For agents.
• Need a password or a code from a person? Never ask in chat: ask through a page.
• Every limit: Limits. The whole API: /openapi.json.