Xác thựcPOST

Tạo phiên ủy quyền nhà cung cấp

Tạo phiên ủy quyền WhatsApp công khai cho bước Passkey bổ sung trong luồng QR. Dùng authorize_url được lưu trữ sẵn hoặc auth_payload.public_key để gọi WebAuthn trực tiếp. Không ghi URL, challenge hay credential vào log công khai hoặc chia sẻ chúng.

https://api.unifyport.ai/v1/accounts/{account_id}/auth-sessions

Tiêu đề

X-Api-Key

stringbắt buộc

API key của không gian làm việc. Không gian làm việc được xác định từ tiêu đề này.

Tham số đường dẫn

account_id

stringbắt buộc

Định danh dùng cho route authentication.

Nội dung yêu cầu

Điểm cuối này không cần nội dung JSON.

Nội dung phản hồi

account_id

string

Tài khoản nhà cung cấp mà phản hồi này tham chiếu tới.

provider

string

Tên canonical provider trong phản hồi. whatsapp-protocol chỉ hỗ trợ xác thực session, hiện hỗ trợ text, image và chi tiết liên hệ; không hỗ trợ reply, mentions, danh sách và thao tác ghi liên hệ, hội thoại hoặc nhóm. Khả dụng phụ thuộc vào adapter đã đăng ký trong môi trường triển khai.

enum: whatsapp

auth_mode

string

Chế độ ủy quyền của phiên. Passkey là nhánh bổ sung của WhatsApp qrcode.

status

string

Trạng thái hiện tại của luồng ủy quyền, ví dụ pending_auth, awaiting_qr_scan, awaiting_code, pending, passkey_required, passkey_pending, passkey_confirmation, passkey_confirmation_sent, authorized hoặc failed.

auth_payload

object

Payload chuẩn cần cho bước hiện tại. QR dùng qr_code; bước xác minh mã dùng type=code; Passkey dùng type=passkey và public_key. Payload của các bước loại trừ nhau không xuất hiện cùng lúc.

authorize_url

string

URL tạm thời được lưu trữ để hoàn tất bước Passkey. Không ghi log hoặc chia sẻ giá trị này.

format: uri

expires_at

string

Dấu thời gian RFC3339 mà sau đó auth_payload hiện tại không còn hợp lệ.

format: date-time

switchable

boolean

Cho biết người dùng có thể chuyển sang chế độ ủy quyền khả dụng khác hay không.

available_auth_modes[]

string[]

Các chế độ ủy quyền có thể chuyển sang an toàn từ phiên hiện tại.

Phản hồi

201

201 Created

Yêu cầu thành công. Xem ví dụ nội dung phản hồi.

400

Bad Request

Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.

401

Unauthorized

Header X-Api-Key thiếu hoặc không hợp lệ.

500

Internal Server Error

Dịch vụ gặp lỗi không mong muốn.

503

Service Unavailable

Dịch vụ backend cần thiết tạm thời không khả dụng.

Yêu cầu

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/auth-sessions \
  -H "X-Api-Key: <YOUR_API_KEY>"

Phản hồi

{
  "data": {
    "account_id": "acc_example",
    "provider": "whatsapp",
    "auth_mode": "qrcode",
    "status": "passkey_required",
    "auth_payload": {
      "type": "passkey",
      "public_key": {
        "challenge": "<BASE64URL_CHALLENGE>"
      }
    },
    "authorize_url": "https://auth.example.com/authorize/whatsapp/<SESSION_TOKEN>",
    "expires_at": "2026-08-12T08:10:00Z",
    "switchable": false,
    "available_auth_modes": ["qrcode"]
  }
}