---
title: "List authorizations"
method: GET
path: "/api/v1/authorizations"
tags: ["Authorizations"]
---

# List authorizations

`GET /api/v1/authorizations`

## Request

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

Get paginated list of authorizations with filtering by status, phone, and channel.

## Query parameters

- `page` integer
- `limit` integer
- `status` 'pending' | 'active' | 'expired' | 'revoked' | 'denied': Status of an authorization
- `phone` string
- `channel` 'whatsapp' | 'telegram' | 'sms' | 'email': Channel authorized for sending confirmations

## Response `200`

List of authorizations

- AuthorizationListResponse
  - `data` Authorization[], required
    - `id` string, required: MongoDB ObjectId
    - `status` 'pending' | 'active' | 'expired' | 'revoked' | 'denied', required: Status of an authorization
    - `hitl_id` string: HITL configuration this authorization is linked to (confirmations scope; absent for identity_challenge scope)
    - `circle_id` string: Circle this authorization is linked to (identity_challenge scope; absent for confirmations scope)
    - `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
    - `label` string, nullable: Owner-assigned human label for this approver (F22); null when unset. Surfaces lead with it, falling back to the masked recipient.
    - `recipient_display_name` string, 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.
    - `enrolled` boolean, 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_id` string: MongoDB ObjectId
    - `proof_token` string: Signed proof of the recipient's decision, minted when they approved or refused, for both scopes. Absent while no decision has been made.
    - `authorized_at` string, date-time
    - `denied_at` string, 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_at` string, date-time, required
    - `revoked_at` string, date-time
    - `revocation_reason` string
    - `confirmations_sent` integer, required
    - `last_used_at` string, date-time
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `pagination` object, required
    - `page` integer, required
    - `limit` integer, required
    - `total` integer, required
    - `total_pages` integer, required

## Other responses

- `401`: Unauthorized

---

[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)