Giao thức OAuth cho phép các khách hàng khác của Notiondesk kết nối ứng dụng của bạn với không gian làm việc của họ mà không cần chia sẻ khóa API. Khách hàng đăng nhập vào Notiondesk, xem xét các yêu cầu của ứng dụng và chấp thuận. Ứng dụng của bạn nhận được mã thông báo truy cập cho API REST của Notiondesk, và khách hàng có thể thu hồi mã thông báo này bất cứ lúc nào. Bài viết này hướng dẫn quy trình đăng ký ứng dụng, chạy quy trình mã ủy quyền OAuth 2.0 với PKCE, làm mới mã thông báo và xử lý lỗi.
Khi nào nên sử dụng OAuth thay vì khóa API?
| Mã thông báo truy cập OAuth | Khóa API không gian làm việc | |
|---|---|---|
| Sử dụng nó cho | Một ứng dụng mà các khách hàng khác của Notiondesk kết nối: một sản phẩm SaaS, một tích hợp thị trường, một công cụ báo cáo. | Tự động hóa bạn chạy cho không gian làm việc của mình: một tập lệnh, một tác vụ theo lịch trình, một bước CI |
| Ai tạo ra nó? | Khách hàng, bằng cách chấp thuận ứng dụng của bạn | Bạn có thể vào Cài đặt > Nhà phát triển > Khóa API. |
| Trọn đời | Mã truy cập: 1 giờ. Mã làm mới: 30 ngày, được gia hạn mỗi khi làm mới. | Cho đến khi hết hạn, được xoay vòng hoặc bị thu hồi. |
| Đã bị thu hồi từ | Cài đặt > Nhà phát triển > Ứng dụng đã kết nối | Cài đặt > Nhà phát triển > Khóa API |
Mọi tuyến API Notiondesk đều chấp nhận cả hai thông tin xác thực và trả lời chúng theo cùng một cách: cùng phạm vi, phản hồi và lỗi.
Những điều ứng dụng của bạn cần biết
| Mục | Giá trị |
|---|---|
| Siêu dữ liệu máy chủ ủy quyền | https://api.notiondesk.so/.well-known/oauth-authorization-server |
| Điểm cuối ủy quyền | https://api.notiondesk.so/oauth/authorize |
| Điểm cuối mã thông báo | https://api.notiondesk.so/oauth/token |
| Điểm cuối đăng ký khách hàng | https://api.notiondesk.so/oauth/register |
| Tài nguyên | https://api.notiondesk.so |
| Phạm vi | read, write, sync, admin |
| Các loại trợ cấp | authorization_code với PKCE và refresh_token |
| Phương pháp PKCE | __ĐƯỢC BẢO TỒN_66__ chỉ |
Hãy đọc các điểm cuối từ tài liệu siêu dữ liệu của máy chủ ủy quyền thay vì mã hóa cứng chúng.
Bước 1: Đăng ký ứng dụng của bạn
Đăng ký một lần với tính năng đăng ký khách hàng động :
Phản hồi 201 Created chứa client_id của bạn và, vì bạn yêu cầu client_secret_post, nên cũng chứa client_secret. Mã bí mật chỉ được hiển thị một lần: hãy lưu trữ nó cùng với các mã bí mật máy chủ khác của bạn.
Với "token_endpoint_auth_method": "none", ứng dụng của bạn là một máy khách công khai không có khóa bí mật và PKCE bảo vệ việc trao đổi mã của nó.
Thay vì đăng ký, bạn có thể sử dụng URL HTTPS của tài liệu siêu dữ liệu khách hàng làm client_id. Notiondesk sẽ tải tài liệu khi khách hàng ủy quyền cho ứng dụng của bạn và lưu vào bộ nhớ đệm trong tối đa năm phút.
Quy tắc URI chuyển hướng
curl -X POST "https://api.notiondesk.so/oauth/register" \
-H "Content-Type: application/json" \
-d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'- Sử dụng
httpshoặchttptrên máy chủ loopback:127.0.0.1,localhosthoặc[::1].
- Lệnh chuyển hướng vòng lặp (loopback redirect) khớp với bất kỳ cổng nào. Bất kỳ lệnh chuyển hướng nào khác phải khớp chính xác.
- Các ký tự đại diện, đoạn mã, thông tin xác thực trước máy chủ (
user@), dấu gạch chéo ngược, ký tự không phải ASCII và máy chủ được mã hóa phần trăm đều bị từ chối.
- Máy chủ mà khách hàng nhìn thấy trên màn hình chấp thuận đến từ URI chuyển hướng của bạn hoặc URL
client_idcủa bạn. Chỉ đăng ký các máy chủ mà bạn sở hữu.
Bước 2: Chuyển khách hàng đến Notiondesk
Tạo một code_verifier ngẫu nhiên, sau đó suy ra code_challenge bằng cách sử dụng hàm băm SHA-256 của trình xác minh, được mã hóa trong base64url ( PKCE ). Chuyển hướng trình duyệt của khách hàng đến:
https://api.notiondesk.so/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
&scope=read%20write
&state=RANDOM_STATE
&code_challenge=YOUR_CODE_CHALLENGE
&code_challenge_method=S256
&resource=https%3A%2F%2Fapi.notiondesk.soresourcelà bắt buộc và phải chính xác làhttps://api.notiondesk.so: chữ thường, không có dấu gạch chéo ở cuối, không có đường dẫn. Giá trị bị thiếu hoặc khác sẽ trả vềinvalid_request.
scopelà một danh sách được phân tách bằng dấu cách. Chỉ yêu cầu các phạm vi mà ứng dụng của bạn sử dụng.
statebảo vệ chống lại tấn công giả mạo yêu cầu liên trang (CSRF). Hãy kiểm tra lại khi khách hàng quay lại.
Mã thông báo được cấp cho API REST Notiondesk chỉ hoạt động với API REST đó. Mã thông báo được cấp cho Workspace MCP sẽ bị API REST từ chối, và ngược lại.
Bước 3: Khách hàng chấp thuận ứng dụng của bạn
Notiondesk hiển thị màn hình chấp thuận. Khách hàng đăng nhập và thấy tên ứng dụng và máy chủ của bạn, không gian làm việc của họ và các phạm vi từ yêu cầu của bạn mà vai trò của họ cho phép. Họ chấp thuận hoặc từ chối toàn bộ yêu cầu.
Các phạm vi quyền mà ứng dụng của bạn có thể nhận được phụ thuộc vào vai trò của khách hàng trong không gian làm việc:
| Vai trò của khách hàng | Phạm vi mà ứng dụng của bạn có thể nhận được |
|---|---|
| Trình xem hoặc Trình quản lý thanh toán | read |
| Biên tập viên | read, write, sync |
| Quản trị viên hoặc chủ sở hữu không gian làm việc | read, write, sync, admin |
admin cho phép ứng dụng của bạn thay đổi thương hiệu của trung tâm trợ giúp, cấu hình các tích hợp có tập lệnh được tải trên trung tâm trợ giúp công khai và xóa các chuyển hướng. Chỉ yêu cầu quyền này nếu ứng dụng của bạn sử dụng các tuyến đường đó.
Khách hàng không thể phê duyệt yêu cầu khi:
- Vai trò của họ không cho phép bất kỳ phạm vi nào bạn yêu cầu;
- Không gian làm việc của họ không có quyền truy cập API. Màn hình xác nhận sau đó hiển thị "Gói không gian làm việc không bao gồm quyền truy cập API." Quyền truy cập API yêu cầu gói Doanh nghiệp.
Sau khi được chấp thuận, trình duyệt sẽ trả về redirect_uri của bạn với code, state và iss, mã định danh của máy chủ ủy quyền Notiondesk. Nếu khách hàng từ chối, quá trình chuyển hướng sẽ mang theo error=access_denied thay thế.
Bước 4: Đổi mã lấy token
Mã giảm giá có hiệu lực trong 60 giây và chỉ sử dụng được một lần:
Bỏ qua client_secret đối với khách hàng công khai. Câu trả lời:
scope liệt kê các phạm vi mà khách hàng đã cấp, có thể ít hơn số lượng bạn yêu cầu. Lưu trữ cả hai mã thông báo trên máy chủ của bạn.
Bước 5: Gọi API Notiondesk
Gửi mã truy cập dưới dạng mã bearer, giống hệt như khóa API:
Phạm vi của mã thông báo bị giới hạn ở vai trò hiện tại của khách hàng phê duyệt: một khách hàng được chuyển sang vai trò Người xem sẽ chỉ để lại ứng dụng của bạn với mã lỗi read, và một tuyến đường cần phạm vi bị thiếu sẽ trả về lỗi 403 insufficient_scope.
Ngân sách giới hạn tỷ lệ và các giá trị Idempotency-Key thuộc về khoản tài trợ. Mỗi lần phê duyệt là một khoản tài trợ mới với ngân sách và khóa riêng, và việc làm mới mã thông báo sẽ giữ lại cả hai.
Bước 6: Làm mới mã truy cập
Mã truy cập có hiệu lực trong một giờ. Trước khi hết hạn, hãy đổi mã làm mới lấy một cặp mã mới:
Mỗi lần làm mới sẽ trả về một mã thông báo làm mới mới có hiệu lực trong 30 ngày và vô hiệu hóa mã thông báo bạn đã gửi. Hãy lưu trữ mã thông báo làm mới mới trước khi sử dụng mã thông báo truy cập mới.
curl -X POST "https://api.notiondesk.so/oauth/token" \
-d grant_type=authorization_code \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d code=THE_CODE \
-d code_verifier=YOUR_CODE_VERIFIER \
-d redirect_uri=https://acme.example/oauth/callback{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "8f3c...",
"scope": "read write"
}curl "https://api.notiondesk.so/sites" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "nd-version: 2026-10-16"curl -X POST "https://api.notiondesk.so/oauth/token" \
-d grant_type=refresh_token \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d refresh_token=THE_REFRESH_TOKENKhách hàng hủy ứng dụng của bạn như thế nào?
Chủ sở hữu không gian làm việc và Quản trị viên có thể xem mọi ứng dụng có quyền truy cập vào không gian làm việc của họ trong Cài đặt > Nhà phát triển > Ứng dụng đã kết nối . Các ứng dụng sử dụng API REST sẽ hiển thị API REST trong cột Quyền truy cập , cùng với tên ứng dụng, người đã cấp quyền, phạm vi quyền và hoạt động gần nhất của ứng dụng. Thu hồi quyền sẽ chấm dứt quyền ngay lập tức: mã thông báo truy cập và mã thông báo làm mới sẽ ngừng hoạt động trong yêu cầu tiếp theo.
Một khoản tài trợ cũng sẽ tự hết hạn:
- sau 30 ngày không làm mới;
- khi mã thông báo làm mới của nó được sử dụng lại.
Trong khi khách hàng phê duyệt thiếu vai trò cần thiết cho tuyến đường hoặc gói không gian làm việc thiếu quyền truy cập API, các yêu cầu sẽ bị từ chối. Chúng sẽ hoạt động trở lại nếu vai trò hoặc gói được cấp lại trước khi thời hạn cấp phép kết thúc.
Khắc phục sự cố Notiondesk OAuth
Các điểm cuối ủy quyền và mã thông báo xử lý các lỗi OAuth tiêu chuẩn, chứ không phải gói lỗi API Notiondesk:
{"error": "invalid_grant", "error_description": "Invalid authorization code."}error | Trạng thái | Khi |
|---|---|---|
invalid_request | 400 | Một tham số bị thiếu hoặc không hợp lệ: resource không xác định, thiếu thử thách PKCE, redirect_uri chưa được đăng ký, máy khách không xác định tại điểm cuối ủy quyền hoặc grant_type không được hỗ trợ. |
invalid_client | 401 | Thông tin bí mật của khách hàng bị thiếu hoặc không chính xác. |
invalid_grant | 400 | Mã hoặc mã thông báo làm mới không xác định, đã hết hạn, đã được sử dụng hoặc bị thu hồi, code_verifier hoặc redirect_uri không khớp, hoặc điểm cuối mã thông báo không biết máy khách. |
server_error | 500 | Notiondesk thất bại; thử lại sau. |
Điểm cuối ủy quyền tự hiển thị các lỗi này và không bao giờ chuyển hướng yêu cầu không hợp lệ đến redirect_uri của bạn. Sự đồng ý bị từ chối chỉ đến ứng dụng của bạn thông qua chuyển hướng error=access_denied.
Các lệnh gọi đến chính API sẽ trả về gói lỗi API Notiondesk . Mã truy cập đã hết hạn hoặc bị thu hồi sẽ trả về mã lỗi 401 authentication_error với thông báo "Khóa API không hợp lệ hoặc bị thiếu.", cùng một thông báo như khi khóa API không thể sử dụng được.
Câu hỏi thường gặp
Tôi có thể gọi API Notiondesk từ một ứng dụng trang đơn có xác thực OAuth không?
Không. Các ứng dụng khách dựa trên trình duyệt không được hỗ trợ. Hãy chạy quy trình OAuth và mọi lệnh gọi API trên máy chủ của bạn, và giữ mã thông báo bên ngoài trình duyệt.
Mã truy cập Notiondesk có thời hạn bao lâu?
Một giờ. Làm mới bằng mã thông báo làm mới, mã này có hiệu lực trong 30 ngày và được thay thế mỗi khi làm mới. Quyền được cấp nếu không được làm mới trong vòng 30 ngày sẽ bị hủy bỏ.
Ứng dụng OAuth của tôi có thể sử dụng Workspace MCP không?
Không. Mã thông báo được cấp cho API REST, với resource=https://api.notiondesk.so, bị Workspace MCP từ chối. Workspace MCP tự cấp mã thông báo riêng cho các máy khách AI.
Tại sao ứng dụng của tôi lại nhận được ít quyền truy cập hơn so với yêu cầu?
Vai trò trong không gian làm việc của khách hàng giới hạn phạm vi quyền. Người biên tập có thể cấp các quyền read, write và sync, nhưng không thể cấp admin. Trường scope trong phản hồi mã thông báo liệt kê những quyền đã được cấp.