Mã thông báo

Token là thông tin xác thực dùng để cấp quyền cho các yêu cầu gửi đến API của Altium 365. Mọi yêu cầu API phải bao gồm một token hợp lệ trong header Authorization.

Token được tạo trong Workspace của bạn tại mục Admin → Developer. Chỉ quản trị viên Workspace mới có thể tạo token.

Các loại token

Có hai loại token, khác nhau về cách sử dụng và các đánh đổi liên quan đến bảo mật.

Access Token tồn tại dài hạn

Một thông tin xác thực duy nhất được dùng trực tiếp làm bearer token trong các yêu cầu API. Bạn cấu hình thời hạn hiệu lực khi tạo – tối đa 1 năm.

Authorization: Bearer {token}

Đây là lựa chọn đơn giản hơn: một giá trị duy nhất, được dùng trực tiếp. Phù hợp với script, tự động hóa và phát triển cục bộ, nơi tính dễ sử dụng quan trọng hơn việc xoay vòng thông tin xác thực.

Hạn chế chính là giá trị token không thay đổi trong suốt thời gian hiệu lực. Nếu bị lộ, token vẫn sẽ hợp lệ cho đến khi hết hạn hoặc bị thu hồi thủ công.

Refresh Token

Một lựa chọn an toàn hơn, tách biệt thông tin xác thực tồn tại dài hạn với thông tin xác thực tồn tại ngắn hạn được dùng trong các yêu cầu API. Khi tạo, bạn sẽ nhận được ba giá trị:

• Client ID – định danh token client

• Client secret – xác thực token client

• Refresh token – thông tin xác thực tồn tại dài hạn

Bạn dùng các giá trị này để đổi lấy một access token tồn tại ngắn hạn bằng cách gọi token endpoint. Access token là giá trị được dùng trong các yêu cầu API. Khi token này hết hạn, bạn yêu cầu một token mới bằng chính refresh token đó.

Refresh token có thời hạn hiệu lực có thể cấu hình, tối đa 1 năm. Các access token mà nó tạo ra có thời gian hiệu lực ngắn.

Cách tiếp cận này phù hợp hơn với các tích hợp trong môi trường production:

• Thông tin xác thực đi kèm với mọi yêu cầu API (access token) chỉ có hiệu lực trong thời gian ngắn

• Bí mật tồn tại dài hạn (refresh token) được lưu trong nơi lưu trữ bảo mật của bạn và không bao giờ được gửi trực tiếp đến API

Xem Sử dụng Refresh Token để biết quy trình trao đổi token.

Chọn loại token

Phạm vi quyền

Mỗi token được gắn với một tập OAuth scopes xác định những thao tác API nào mà token có thể cấp quyền. Phạm vi quyền được cấu hình khi token được tạo và không thể thay đổi về sau.

Xem OAuth Scopes để biết danh sách đầy đủ các phạm vi quyền khả dụng và cách chúng ánh xạ tới các khả năng của API.

Thời hạn hiệu lực của token

Cả hai loại token đều có thời hạn hiệu lực có thể cấu hình lên đến 1 năm, được đặt khi tạo. Không có cơ chế gia hạn tự động – một khi token hết hạn, phải tạo token mới.

Đối với refresh token, thời hạn hiệu lực áp dụng cho chính refresh token đó. Các access token mà nó tạo ra có thời hạn ngắn hơn và cố định.

Thu hồi token

Token có thể được thu hồi từ Admin → Developer bất kỳ lúc nào. Việc thu hồi token sẽ làm token đó mất hiệu lực ngay lập tức – mọi yêu cầu API sử dụng token đó sẽ thất bại với lỗi ủy quyền.