Confirmations

Create confirmation

Create a new HITL confirmation request. Dispatches approval message via configured HITL channels.

post/api/v1/confirmations

Request

  • Base URL: https://api.proof.holdings
  • URL: https://api.proof.holdings/api/v1/confirmations
  • Auth: HTTP bearer

Request body

hitl_idstring required

HITL configuration to use for this confirmation

messagestring required

Encrypted confirmation message (ciphertext envelope JSON)

proof_expiry_daysinteger

Per-request proof expiry override in days (1-365). Overrides default (confirmation window).

Example request

{
  "hitl_id": "507f1f77bcf86cd799439011",
  "message": "{\"v\":1,\"alg\":\"RSA-OAEP-256+AES-256-GCM\",\"ek\":\"...\",\"iv\":\"...\",\"ct\":\"...\",\"tag\":\"...\",\"kid\":\"...\"}",
  "proof_expiry_days": 365
}

Response

Confirmation created and dispatched

idstring required

MongoDB ObjectId

hitl_idstring required

HITL configuration used for this confirmation

messagestring required

The stored ciphertext envelope, echoed back verbatim. The server never sees the plaintext, so this is never the human sentence — the approver decrypts it in their browser.

status'pending' | 'approved' | 'denied' required

Status of a confirmation request. A confirmation that times out is denied, with response.channel system and response.text timeout.

timeout_atstring date-time nullable

When this confirmation will time out

proof_tokenstring nullable

Signed proof of an approver's decision, approval or denial alike; null while pending and for a system denial (response.channel is system)

resolved_atstring date-time nullable
created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "hitl_id": "507f1f77bcf86cd799439011",
  "message": "{\"v\":1,\"alg\":\"RSA-OAEP-256+AES-256-GCM\",\"ek\":\"...\",\"iv\":\"...\",\"ct\":\"...\",\"tag\":\"...\",\"kid\":\"...\"}",
  "status": "pending",
  "response": {
    "action": "approve",
    "channel": "telegram"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.