Token

Token là thông tin xác thực dùng để cấp quyền cho các yêu cầu tới API của Altium 365. Mọi yêu cầu API đều 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 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 ở cách sử dụng và những đánh đổi về bảo mật.

Access Token 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 của nó 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. Nó phù hợp cho script, tự động hóa và phát triển cục bộ khi 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ộ, nó vẫn có hiệu lực 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 dài hạn với thông tin xác thực 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 dài hạn

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

Refresh token có thời hạn cấu hình được lên đến 1 năm. Các access token mà nó tạo ra có thời hạn ngắn.

Cách tiếp cận này phù hợp hơn cho các tích hợp production:

• Thông tin xác thực đi kèm với mọi yêu cầu API (access token) có thời hạn ngắn

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

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

Chọn loại token

Scope

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

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

Thời hạn token

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

Đối với refresh token, thời hạn này á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, cố định là 1 giờ.

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ẽ ngay lập tức làm nó mất hiệu lực – mọi yêu cầu API sử dụng token đó sẽ thất bại với lỗi phân quyền.