Tích hợp và API

Kết nối script, plugin cho editor, extension trình duyệt hay ứng dụng của riêng bạn. Một client cần hai bí mật riêng biệt:

Bí mật	Mở được gì	Lấy từ đâu
API token (`nf_…`)	Nói chuyện với API: tải và lưu ghi chú đã mã hoá	NoteFlare → Tài khoản → Tích hợp
Passphrase	Đọc và ghi nội dung ghi chú	Bạn. Nó không bao giờ rời client

Chỉ có token thì không đọc được gì.

Tạo token

Vào Tài khoản → Tích hợp và tạo token. Token chỉ hiện một lần.

Scope	Làm được	Không làm được
`read`	Đọc vault, liệt kê và tải ghi chú	Tạo, sửa hay xoá bất cứ thứ gì
`write`	Mọi thứ `read` làm được, cộng với tạo, sửa, bỏ vào thùng rác, khôi phục và xoá ghi chú	Quản lý token hay đổi passphrase

Token có thể hết hạn sau 30 ngày, 90 ngày hoặc một năm, và có thể thu hồi bất cứ lúc nào.

SDK TypeScript

import { NoteFlareClient } from '@noteflare/client'

const nf = new NoteFlareClient({ url: 'https://notes.example.com', token: 'nf_…' })
await nf.unlock(passphrase)                       // giải mã vẫn diễn ra ở phía bạn
await nf.create({ title: 'Từ script của tôi', body: '- [ ] chạy rồi' })

CLI

export NOTEFLARE_URL=https://notes.example.com
export NOTEFLARE_TOKEN=nf_…            # token có quyền write
node packages/cli/bin/noteflare.mjs ls
echo "- [ ] Mang áo khoác" | node packages/cli/bin/noteflare.mjs append trip
node packages/cli/bin/noteflare.mjs export ./backup    # Markdown nhập lại được

CLI sẽ hỏi passphrase, hoặc đọc từ NOTEFLARE_PASSPHRASE.

Cho client API đi qua Cloudflare Access

Access bảo vệ cả domain bằng trang đăng nhập trên trình duyệt, thứ mà script không vượt qua được. Chọn một trong hai cách sau cho đường dẫn /api/v1.

Cách A: Bypass (đơn giản nhất). Mọi request tới /api/v1 vẫn phải kèm token NoteFlare.

Trong Zero Trust → Access → Applications, thêm một application Self-hosted.
Domain: domain NoteFlare của bạn. Path: api/v1.
Policy: action Bypass, include Everyone.

Cách B: Service Auth (thêm một lớp bảo vệ). Request cần cả service token của Cloudflare Access lẫn token NoteFlare.

Zero Trust → Access → Service Auth → Create service token. Chép Client ID và Secret.
Thêm một application Self-hosted cho path api/v1 với policy Service Auth bao gồm service token đó.
Gửi CF-Access-Client-Id và CF-Access-Client-Secret trong mọi request.

Tài liệu đầy đủ

Hướng dẫn API trên GitHub (tiếng Anh)Các endpoint, đồng bộ, xử lý xung đột, lỗi và giới hạn, và định dạng mã hoá chính xác kèm ví dụ Python.

Spec OpenAPI 3.1 có tại /api/v1/openapi.json trên chính bản triển khai của bạn.