Authorizations

Update authorization label

Set or clear the owner-assigned human label for this authorization (F22). label: null or an empty string clears it.

patch/api/v1/authorizations/{id}

Request

  • Base URL: https://api.proof.holdings
  • URL: https://api.proof.holdings/api/v1/authorizations/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

MongoDB ObjectId

Example:507f1f77bcf86cd799439011

Request body

labelstring nullable required

Owner-assigned human label ("Sarah — CFO"). null or an empty string clears it.

Example request

{
  "label": "Sarah — CFO"
}

Response

Updated authorization

idstring required

MongoDB ObjectId

status'pending' | 'active' | 'expired' | 'revoked' | 'denied' required

Status of an authorization

hitl_idstring

HITL configuration this authorization is linked to (confirmations scope; absent for identity_challenge scope)

circle_idstring

Circle this authorization is linked to (identity_challenge scope; absent for confirmations scope)

recipientstring nullable

Channel-specific recipient identifier (chat_id for Telegram, phone or BSUID for WhatsApp)

phonestring nullable
bsuidstring nullable

WhatsApp Business-Scoped User ID

channel'whatsapp' | 'telegram' | 'sms' | 'email' required

Channel authorized for sending confirmations

scope'confirmations' | 'identity_challenge' required

Scope of the authorization. identity_challenge is the Proof of Me scope.

business_namestring required
labelstring nullable

Owner-assigned human label for this approver (F22); null when unset. Surfaces lead with it, falling back to the masked recipient.

recipient_display_namestring nullable required

The approver's own messenger name ("First Last @username"), captured when they approved over Telegram; null when none was captured. Chosen by the approver, not verified.

enrolledboolean required

Whether the approver has enrolled an encryption key. A confirmation can be sealed to an approver only once this is true; consent alone (status: active) is not enough.

verification_idstring

MongoDB ObjectId

proof_tokenstring

Signed proof of the recipient's decision, minted when they approved or refused, for both scopes. Absent while no decision has been made.

authorized_atstring date-time
denied_atstring date-time

When the recipient refused — the mirror of authorized_at for a denied row (a challenger cancellation stamps it too). Absent unless the authorization was denied; before it existed such a row carried no decision time at all, only updated_at.

expires_atstring date-time required
revoked_atstring date-time
revocation_reasonstring
confirmations_sentinteger required
last_used_atstring date-time
created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "status": "active",
  "hitl_id": "507f1f77bcf86cd799439011",
  "circle_id": "507f1f77bcf86cd799439011",
  "recipient": "123456789",
  "phone": "+15551234567",
  "channel": "whatsapp",
  "scope": "confirmations",
  "business_name": "Acme Corp",
  "label": "Sarah — CFO",
  "recipient_display_name": "Sarah @sarah_cfo",
  "enrolled": true,
  "verification_id": "507f1f77bcf86cd799439011",
  "confirmations_sent": 5
}

Changes

No recorded changes to this operation across all 1 revision of this API.