---
title: "First-seen pin confirmation (owner + step-up)"
method: POST
path: "/vaults/v1/{vault_id}/recipients/{principal_id}/confirm"
tags: ["vault"]
---

# First-seen pin confirmation (owner + step-up)

`POST /vaults/v1/{vault_id}/recipients/{principal_id}/confirm`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/vaults/v1/{vault_id}/recipients/{principal_id}/confirm`
- Auth: one of:
  - API key in header `SIGN-IN-WITH-X`
  - HTTP bearer

Owner + step-up (`gitvault.rotate`, protocol rev 42 D197). Issues a `recipient_confirmation_receipt` with `purpose:"first_pin"` for a principal with NO currently-admitted pin on this vault — a principal who already has one must use the repin route instead (`409 RECIPIENT_SET_MISMATCH`). The receipt is single-use and must be cited by the matching entry of the `recipient_pin_manifest` the rotation eventually admits. IDEMPOTENT (rev 43 D206): a repeated call for the identical (principal, new_fingerprint, currently-effective base manifest, recipient_state_version) tuple returns `200` with the SAME previously-issued receipt rather than minting a second one.

## Path parameters

- `vault_id` string, required
- `principal_id` string, required

## Headers

- `SIGN-IN-WITH-X` string, required

## Request body

- object
  - `new_fingerprint` string, required: The recipient's `ek_<32 hex>` encryption-key fingerprint being pinned.

## Response `200`

rev 43 D206 — idempotent replay of the SAME previously-issued receipt for this identical tuple

- object

## Other responses

- `201`: A genuinely fresh recipient_confirmation_receipt
- `400`: VALIDATION_FAILED — new_fingerprint is not a well-formed ek_… fingerprint
- `403`: VAULT_ACCESS_DENIED
- `409`: RECIPIENT_SET_MISMATCH — this principal already has a currently-admitted pin; use the repin route

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)