Bảo mật & dữ liệu

Quản lý API key

• API key (alt_live_...) chỉ hiển thị một lần khi tạo. Chúng tôi chỉ lưu keyed hash của secret nên không thể hiển thị lại — mất key thì bạn buộc phải xoay vòng key mới.
• Webhook signing secret (whsec_...) cũng chỉ hiển thị một lần. Chúng được lưu ở dạng mã hóa (AES-256-GCM) và chỉ được giải mã để ký các lần gửi đi — không bao giờ hiển thị lại. Muốn xoay vòng thì hãy tạo lại endpoint, khi đó một secret mới sẽ được cấp.
• Hãy lưu key trong secret manager. Đừng bao giờ nhúng key vào code phía client, ứng dụng di động hay repository.
• Xoay vòng key trong console: phát hành key mới trên cùng một integration, chuyển hệ thống của bạn sang key mới, rồi thu hồi key cũ. Việc thu hồi có hiệu lực ngay lập tức.
• Bạn có thể đặt thời hạn khi tạo key; key hết hạn sẽ tự động bị từ chối.
• Mỗi hệ thống một key. Hãy tách staging khỏi production để việc thu hồi key bên này không làm hỏng bên kia.
• Không có sandbox hay chế độ thử nghiệm — mọi key được cấp đều là key thật và đọc ghi chú thật. Hãy dùng integration riêng cho staging và production; còn nếu muốn kiểm tra receiver mà không phải chờ một bản ghi âm thật, hãy dựa vào sự kiện xác minh được gửi khi tạo endpoint hoặc nhấn "Send test" trong console.

Dữ liệu mỗi tích hợp có thể truy cập

• Integration cá nhân chỉ thấy ghi chú cá nhân của chủ sở hữu. Integration teamspace chỉ thấy những ghi chú được chia sẻ vào teamspace đó — không bao giờ thấy ghi chú cá nhân của thành viên.
• Chỉ chủ sở hữu teamspace mới có thể tạo integration cho teamspace.
• Ghi chú nằm ngoài phạm vi của credential sẽ trả về 404 — API không tiết lộ ghi chú đó có tồn tại hay không.
• Khi một ghi chú ra khỏi phạm vi của bạn, bạn sẽ nhận note.deleted (reason: access_lost) và ghi chú đó biến mất khỏi danh sách. Hãy xóa hoặc chặn truy cập vào bản sao bạn đang lưu.

Phạm vi quyền (scope)

Chỉ cấp những quyền mà tích hợp thực sự cần. Request yêu cầu quyền chưa được cấp cho API key sẽ thất bại với 403 insufficient_scope.

Giới hạn request API

• 120 request mỗi phút cho mỗi key. Vượt hạn mức sẽ nhận 429 rate_limited kèm header Retry-After — hãy chờ ít nhất khoảng thời gian đó trước khi thử lại.
• Hãy ưu tiên webhook kết hợp đồng bộ tăng dần (updated_after) thay vì polling liên tục với chu kỳ ngắn.
• Dùng ETag / If-None-Match khi đọc ghi chú, bản chép lời và bản tóm tắt — phản hồi 304 rẻ cho cả hai phía.

Quyền riêng tư

• Bản chép lời và bản tóm tắt là nội dung của người dùng và có thể chứa dữ liệu cá nhân. Chỉ lấy những gì integration của bạn cần, và bảo vệ những gì bạn lưu trữ.
• Hãy tôn trọng thao tác xóa: khi nhận note.deleted (với bất kỳ lý do nào), hãy xóa hoặc chặn truy cập vào bản sao bạn đang lưu. Đối soát định kỳ phòng khi bạn bỏ lỡ sự kiện.
• URL webhook phải là endpoint HTTPS công khai. Các địa chỉ nội bộ, loopback và cloud-metadata đều bị từ chối, và chúng tôi không đi theo redirect.
• Việc truy cập API yêu cầu workspace chứa integration đó có gói đăng ký đang hoạt động; nếu không, request sẽ thất bại với 403 plan_required.
• Xem Chính sách bảo mật của chúng tôi để biết Alt xử lý dữ liệu người dùng như thế nào.