Ủy quyền tài khoản

Trạng thái xác thực

Trả về trạng thái luồng xác thực hiện tại, gồm code, QR, Passkey, mật khẩu, import session hoặc đã xác thực. Với Passkey, trạng thái có thể là passkey_required, passkey_pending, passkey_confirmation hoặc passkey_confirmation_sent; auth_payload.public_key chứa WebAuthn challenge và auth_payload cũng có thể chứa lời nhắc xác nhận. expires_at cho biết khi payload hết hiệu lực.

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/auth

Trước khi gọi

Dùng X-Api-Key của workspace sở hữu tài nguyên trên máy chủ. Thay mọi giá trị mẫu trước khi chạy.

Nguồn tham số

account_id: Lấy data.id từ phản hồi tạo hoặc truy vấn tài khoản. ID thuộc workspace của X-Api-Key. Lấy tài khoản

Tham số yêu cầu

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.

Hiểu kết quả

Đọc trường phản hồi và trạng thái HTTP được mô tả. Thành công 204 không có nội dung; dùng X-Request-Id để chẩn đoán. Xem thao tác liên quan cho bước tiếp theo.

Phản hồi 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_qr_scan",
    "auth_fields": [
      {
        "type": "qr_code",
        "required": true
      }
    ],
    "auth_payload": {
      "qr_code": "https://example.com/qr"
    },
    "expires_at": "2026-01-01T00:00:00Z",
    "last_error": ""
  }
}

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.

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_fields[]

object[]

Mô tả những gì bước tiếp theo yêu cầu — mỗi mục mang một type và việc nó có bắt buộc hay không.

type

string

Loại dữ liệu đầu vào cần cho bước xác thực tiếp theo, như code hoặc password.

required

boolean

Dữ liệu xác thực này có bắt buộc phải cung cấp hay không.

label

string

Nhãn hiển thị do provider cung cấp, nếu có.

placeholder

string

Gợi ý nhập liệu do provider cung cấp, nếu có.

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.

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

last_error

string

Lỗi xác thực gần nhất, hoặc chuỗi rỗng khi không có lỗi nào.

Phản hồi

200

200 OK

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

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.

Khi yêu cầu thất bại

Kiểm tra HTTP và error.code/numeric_code, giữ request_id. Sửa tham số, tiếp tục xác thực hoặc kiểm tra runtime tùy nguyên nhân. Xác nhận kết quả cũ trước khi thử lại thao tác gửi hoặc ghi. Tham chiếu mã lỗi

invalid_request · 10000 · 400: Kiểm tra trường bắt buộc, định dạng và điều kiện kênh rồi sửa yêu cầu.
invalid_api_key · 11001 · 401: Kiểm tra X-Api-Key và workspace còn hoạt động.