# 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](/for-agents.md#2-get-a-key-and-name-the-recipient).

## 2. Create, naming that key

```bash
# 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

```bash
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.

```bash
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](/limits.md#errors-retries-and-headers)).
- CI jobs, servers (no-view) and people: the other quick-starts in [For agents](/for-agents.md#quick-starts-the-four-vault-to-endpoint-shapes).
- Need a password or a code from a person? Never ask in chat: [ask through a page](/for-agents.md#7-ask-a-person-for-a-password-or-a-code).
- Every limit: [Limits](/limits.md). The whole API: [/openapi.json](/openapi.json).