---
title: "Create authorization"
method: POST
path: "/api/v1/authorizations"
tags: ["Authorizations"]
---

# Create authorization

`POST /api/v1/authorizations`

## Request

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

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

## Request body

- CreateAuthorizationBody: Request body for creating an authorization
  - `hitl_id` string, required: HITL configuration to link this authorization to
  - `recipient` string, required: Channel-specific recipient identifier (chat_id for Telegram, phone for WhatsApp/BSUID)
  - `phone` string, required: Target phone number in E.164 format
  - `bsuid` string: 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_name` string, required: Business name displayed to user during authorization
  - `business_profile_id` string: Public profile ID for branding
  - `expires_in` integer: Expiry in seconds (max 90 days, default 90 days)

## Response `201`

Authorization created

- CreateAuthorizationResponse: Response from creating an authorization request
  - `id` string, required: MongoDB ObjectId
  - `status` 'pending' | 'active' | 'expired' | 'revoked' | 'denied', required: Status of an authorization
  - `hitl_id` string, required: HITL configuration this authorization is linked to
  - `recipient` string, nullable: Channel-specific recipient identifier (chat_id for Telegram, phone or BSUID for WhatsApp)
  - `phone` string, nullable
  - `bsuid` string, 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_name` string, required
  - `authorization_url` string, uri, required: URL to send to the user for authorization
  - `expires_at` string, date-time, required
  - `created_at` string, date-time, required

## Other responses

- `400`: Validation error
- `402`: card_required. Only once billing is live: a free account with no card on file that has used its included proofs and the 50-proof grace this month is refused new proof requests until a card is added (add_card_url). Proofs already issued keep working. The error carries add_card_url, used, included and hard_limit.
- `403`: `profile_mismatch` — a project-bound API key named another sub-account; it acts for its own sub-account only.
- `409`: Active authorization already exists for this phone+channel

---

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