Authorizations

Create authorization

Create a new authorization request. The user must authorize a channel before confirmations can be sent via that channel.

post/api/v1/authorizations

Request

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

Request body

hitl_idstring required

HITL configuration to link this authorization to

recipientstring required

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

phonestring required

Target phone number in E.164 format

bsuidstring

WhatsApp Business-Scoped User ID (alternative to phone for WhatsApp channel)

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

Channel authorized for sending confirmations

scope'confirmations'

Defaults to confirmations. Identity challenges are created through POST /identity-challenges.

business_namestring required

Business name displayed to user during authorization

business_profile_idstring

Public profile ID for branding

expires_ininteger

Expiry in seconds (max 90 days, default 90 days)

Example request

{
  "hitl_id": "507f1f77bcf86cd799439011",
  "recipient": "123456789",
  "phone": "+15551234567",
  "bsuid": "US.abcdef1234567890",
  "channel": "whatsapp",
  "business_name": "Acme Corp",
  "business_profile_id": "507f1f77bcf86cd799439011",
  "expires_in": 7776000
}

Response

Authorization created

idstring required

MongoDB ObjectId

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

Status of an authorization

hitl_idstring required

HITL configuration this authorization is linked to

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
authorization_urlstring uri required

URL to send to the user for authorization

expires_atstring date-time required
created_atstring date-time required

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "status": "active",
  "hitl_id": "507f1f77bcf86cd799439011",
  "recipient": "123456789",
  "phone": "+15551234567",
  "channel": "whatsapp",
  "scope": "confirmations",
  "business_name": "Acme Corp",
  "authorization_url": "https://verify.proof.holdings/auth/abc123"
}

Changes

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