Xác thực với API Notiondesk bằng khóa API.

Mỗi yêu cầu API Notiondesk đều được xác thực bằng mã thông báo bearer: khóa API không gian làm việc hoặc mã thông báo truy cập OAuth cho các ứng dụng hoạt động thay mặt cho các khách hàng Notiondesk khác. Bài viết này hướng dẫn cách tạo khóa API Notiondesk, chọn phạm vi của nó, gửi nó cùng với các yêu cầu của bạn, và xoay vòng hoặc thu hồi nó.

Hãy sử dụng khóa API cho các tác vụ tự động hóa bạn chạy trong không gian làm việc của riêng mình: một tập lệnh, một công việc theo lịch trình, một bước CI hoặc một công cụ nội bộ. Nếu bạn đang xây dựng một ứng dụng mà các khách hàng khác kết nối đến, hãy sử dụng OAuth .

Trước khi bạn bắt đầu

• Không gian làm việc của bạn đang sử dụng gói Doanh nghiệp.

• Bạn là chủ sở hữu không gian làm việc hoặc là quản trị viên.

Tạo khóa API Notiondesk

1. Trong bảng điều khiển Notiondesk của bạn, hãy nhấp vào Cài đặt .

2. Trong mục Workspace , mở Developers , sau đó chọn API keys .

3. Nhấp vào Tạo khóa .

4. Nhập nhãn cho biết mục đích của khóa, ví dụ: CI automation hoặc Redirect import.

5. Trong mục Phạm vi (Scopes) , chỉ chọn những phạm vi mà quá trình tích hợp cần. Xem phần Chọn đúng phạm vi (Choose the right scopes) .

6. Chọn thời hạn sử dụng : 30 ngày , 90 ngày , 1 năm hoặc không giới hạn thời gian .

7. Nhấp vào Tạo .

8. Nhấp vào "Sao chép khóa" và lưu khóa vào trình quản lý bí mật hoặc biến môi trường của bạn.

9. Nhấp vào "Tôi đã lưu khóa" .

Chìa khóa chỉ được hiển thị một lần. Nếu bạn làm mất nó, hãy xoay chìa khóa để nhận được một bí mật mới.

Lưu ý: Nếu nút Tạo khóa hiển thị biểu tượng khóa và chú thích "Có sẵn trên các gói có quyền truy cập API.", thì gói của bạn không bao gồm API. Nhấp vào đó sẽ mở các tùy chọn nâng cấp.

Chọn phạm vi phù hợp

Phạm vi (scope) là quyền được gắn với một khóa. Mỗi tuyến API Notiondesk yêu cầu một phạm vi, và một khóa có thể chứa nhiều phạm vi.

Hãy cấp cho mỗi phép tích hợp tập hợp phạm vi nhỏ nhất mà nó cần:

Vai trò trong không gian làm việc hạn chế một yếu tố quan trọng như thế nào?

Một chiếc chìa khóa không bao giờ làm được nhiều hơn những gì người tạo ra nó có thể làm trong không gian làm việc của bạn.

Nếu vai trò của người tạo thay đổi, phạm vi hiệu lực của khóa cũng thay đổi theo. Nếu người tạo rời khỏi không gian làm việc, khóa sẽ ngừng hoạt động. Quản lý vai trò trong phần "Cách mời thành viên nhóm" .

Gửi khóa kèm theo mỗi yêu cầu

Gửi khóa trong tiêu đề Authorization với lược đồ Bearer:

Một mã 200 OK kèm theo danh sách các trung tâm trợ giúp của bạn xác nhận rằng khóa hoạt động. Một khóa hoạt động cho mọi trung tâm trợ giúp trong không gian làm việc của nó.

Yêu cầu tương tự trong JavaScript:

Và trong Python:

Hãy giữ an toàn khóa API Notiondesk của bạn.

curl "<https://api.notiondesk.so/sites>" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

const response = await fetch("<https://api.notiondesk.so/sites>", {
  headers: {
    Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
    "nd-version": "2026-10-16",
  },
});

const sites = await response.json();

import os
import requests

response = requests.get(
    "<https://api.notiondesk.so/sites>",
    headers={
        "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
        "nd-version": "2026-10-16",
    },
)
sites = response.json()

• Hãy lưu trữ khóa trên máy chủ của bạn. Tuyệt đối không đặt khóa vào mã trình duyệt, ứng dụng di động hoặc kho lưu trữ công khai.

• Hãy lưu trữ các khóa trong biến môi trường hoặc trình quản lý bí mật, chứ không phải trong mã nguồn.

• Tạo một khóa riêng cho mỗi tích hợp, với nhãn riêng, để bạn có thể thu hồi một khóa mà không ảnh hưởng đến các khóa khác.

• Chọn thời hạn hết hạn cho các khóa được sử dụng bởi các tập lệnh tạm thời.

• Hãy xoay chìa khóa khi có người biết cách sử dụng nó rời khỏi nhóm của bạn.

• Kiểm tra cột " Lần sử dụng cuối" và thu hồi các khóa mà không ai sử dụng.

Xoay hoặc thu hồi khóa

Mở Cài đặt > Nhà phát triển > Khóa API và sử dụng menu ở cuối hàng của khóa đó.

Thao tác Rotate thay thế khóa bí mật. Xác nhận bằng Rotate : khóa bí mật hiện tại sẽ ngừng hoạt động ngay lập tức và khóa bí mật mới sẽ được hiển thị một lần. Cập nhật tích hợp của bạn ngay lập tức. Khóa đã hết hạn không thể được xoay vòng; thay vào đó hãy tạo khóa thay thế.

Lệnh Revoke sẽ vô hiệu hóa khóa vĩnh viễn. Xác nhận bằng lệnh Revoke : các tự động hóa sử dụng khóa này sẽ ngừng hoạt động ngay lập tức và không thể hoàn tác.

Khắc phục sự cố xác thực

WWW-Authenticate: Bearer error="insufficient_scope", scope="sync"

Câu hỏi thường gặp

Tiếp theo là gì?

• Bắt đầu sử dụng API REST Notiondesk

• Kết nối ứng dụng của bạn với Notiondesk bằng OAuth

• Xử lý các lỗi API, giới hạn tỷ lệ và các lần thử lại của Notiondesk