Ứng dụng & OAuth

Phần mềm của bạn phục vụ nhiều trại? Tạo một app: mỗi trại tự bấm Cho phép, bạn nhận token đúng scope trại đó cấp. Chỉ phục vụ trại của mình thì dùng API key là đủ.

	API key	App (OAuth)
Ai tạo	Chủ trại, trong app	Bạn, ở Ứng dụng của tôi
Dùng cho	Một trại	Nhiều trại — mỗi trại tự cho phép
Chứng từ	`nfk_…`	App ID `nfa_…` + App Secret `nfs_…` ⇒ Access token 15′
Duyệt	Không cần	Không: Development mode ≤ 3 trại của bạn; Publish = máy kiểm tự động

Tạo app

Mở Ứng dụng của tôi › Tạo app — chọn Use cases, nhận App ID + App Secret ngay (App Secret hiện một lần). App ở Development mode: bạn và thành viên app cài được vào tối đa 3 trại.

Cho trại cài — liên kết cài trả code

Gắn liên kết cài vào nút "Kết nối NextFarm". Trại chọn scope, bấm Cho phép rồi được chuyển về Redirect URI kèm code (60 giây, dùng một lần) và state của bạn.

Liên kết cài

https://app.nextfarm.vn/vi/workspace/manage/apps/install?client_id=nfa_…&redirect_uri=https://abc.vn/nextfarm/callback&state=<state>

Trại cho phép xong ⇒ trình duyệt về

https://abc.vn/nextfarm/callback?code=nfc_7Qx…&state=<state>

Đổi code lấy token + workspace_id (máy chủ của bạn)

Kiểm state khớp rồi đổi code bằng App Secret. Lưu workspace_id — đó là trại vừa cài.

POST /api/v1/iam/oauth/token

curl -X POST https://api-prod.nextfarm.vn/api/v1/iam/oauth/token \
  -d grant_type=authorization_code \
  -d code=nfc_7Qx… \
  -d redirect_uri=https://abc.vn/nextfarm/callback \
  -d client_id=nfa_… -d client_secret=nfs_…

Trả về

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 900,
  "scope": "harvest.harvest.view harvest.trace.view", "workspace_id": "6b0e6dae-…" }

Code dùng lại lần hai ⇒ invalid_grant và mọi token của lượt cài đó bị thu hồi (dấu hiệu lộ code).

Token các lần sau: client_credentials

Token sống 15 phút. Hết thì xin lại bằng App ID + App Secret + workspace_id đã lưu.

Lệnh mẫu

curl -X POST https://api-prod.nextfarm.vn/api/v1/iam/oauth/token \
  -u "nfa_…:nfs_…" \
  -d grant_type=client_credentials \
  -d workspace_id=6b0e6dae-…

Gọi API

curl https://api-prod.nextfarm.vn/api/v1/harvest/harvest-records?page_size=5 \
  -H "Authorization: Bearer eyJ…"

Test Console

Ở trang app › Test Console: Generate Access Token cho trại đã cài (máy chủ NextFarm sinh, App Secret không vào trình duyệt), gọi thử bằng API Explorer nhúng, dựng lại trang trại mẫu, gửi thử app.ping.

Publish

Bấm Publish: máy chạy Publish checklist 12 mục (hồ sơ + logo + mô tả ≥ 50 ký tự, email hỗ trợ nhận thư, web + Privacy Policy mở được, Redirect URI https, Webhooks trả 2xx cho app.ping, scope trong danh mục, ≥ 20 lượt gọi thành công và ≥ 3 lệnh khác nhau trong 7 ngày, lỗi 4xx < 30%, tài khoản xác thực ≥ 3 ngày, không bị báo cáo / tạm dừng). Đạt hết là Live ngay (Auto-checked) — không người duyệt. Verified by NextFarm do NextFarm gắn cho đối tác ký hợp đồng.

Chi tiết

Scope cấp = app xin ∩ danh mục máy ∩ quyền người bấm cài. Không scope nào điều khiển thiết bị hay quản trị.
Bạn thêm scope ở Use cases ⇒ trại đang cài giữ scope cũ tới khi đồng ý lại. Bỏ scope ⇒ token sau mất scope đó ngay.
Gỡ app, đổi scope, xoá app hoặc app bị tạm dừng ⇒ token đang có bị chặn ngay (401 token_revoked).
Xoay App Secret: secret cũ còn dùng 24 giờ.
Rate limit 600 lượt/phút cho mỗi app × trại; Rate limit.
Sự kiện cài/gỡ (app.installed …) và sự kiện dữ liệu gửi tới Callback URL của app: Webhooks.

Lỗi	Nghĩa
`400 invalid_grant`	code sai / quá 60 giây / đã dùng / redirect_uri lệch
`401 invalid_client`	App ID / App Secret sai hoặc app bị tạm dừng
`403 access_denied`	Trại chưa cài / đã gỡ app
`403 invalid_scope`	Xin scope trại chưa cấp

App Secret chỉ ở máy chủ của bạn — không nhúng vào app di động hay mã chạy trên trình duyệt.

Luật bảo mật đầy đủ: Bảo mật →