Token API cá nhân

Token API cá nhân cho phần mềm của chính khách (module WHMCS, script quản lý tên miền, công cụ riêng…) gọi API Tino mà không cần đăng nhập. Khách tự tạo token ở Tino ID, chọn quyền, hạn dùng và IP được gọi; phần mềm gửi token trong header Authorization: Bearer tinopat_… tới gateway https://api.tino.vn/v1/<route>.

Cập nhật: 2026-10-27.

Khi nào dùng

Bạn cần	Dùng
Phần mềm của chính bạn gọi API bằng tài khoản Tino của bạn	Token API cá nhân (`tinopat_`)
Ứng dụng của bạn phục vụ nhiều khách Tino, mỗi khách tự đăng nhập và đồng ý	Đăng nhập bằng Tino (`tinoat_`)
Claude, ChatGPT làm việc với tài khoản Tino của bạn	Kết nối MCP: đăng nhập OAuth, không cần token
Ứng dụng MCP khác (Cursor, VS Code, n8n…)	Kết nối MCP: đăng nhập OAuth (ứng dụng tự đăng ký); token API cá nhân khi ứng dụng không hỗ trợ OAuth của MCP hoặc chạy trên máy chủ không mở được trình duyệt

Chỉ token API cá nhân mới mang được quyền domains:owner (lấy mã EPP, đổi chủ thể tên miền); ứng dụng OAuth không bao giờ được cấp quyền này.

Tạo token

Đăng nhập Tino ID, mở https://auth.tino.vn/me/security, mục Token API, bấm Tạo token.
Đặt tên token (1–64 ký tự), ví dụ "Module WHMCS".
Chọn quyền: ít nhất một quyền trong bảng dưới. Chọn quyền ghi của một nhóm thì giao diện chọn kèm quyền đọc cùng nhóm.
Chọn hạn dùng: 30 ngày, 90 ngày, 1 năm (mặc định) hoặc không hết hạn.
Giới hạn IP (không bắt buộc, trừ khi chọn domains:owner): các địa chỉ IPv4, IPv6 hoặc dải CIDR, cách nhau dấu cách hoặc dấu phẩy, tối đa 20. Để trống: gọi được từ mọi IP.
Chép token ngay: token chỉ hiện một lần, khi vừa tạo. Tino chỉ lưu bản băm SHA-256; danh sách token chỉ còn 4 ký tự cuối để nhận ra.

Mỗi tài khoản đăng nhập có tối đa 20 token. Token có dạng tinopat_ + 43 ký tự (base64url).

Quyền	Cho phép
`profile:read`	Xem thông tin tài khoản
`profile:write`	Sửa thông tin tài khoản
`services:read`	Xem dịch vụ, gồm cả thông tin đăng nhập dịch vụ
`services:write`	Quản lý dịch vụ
`domains:read`	Xem tên miền
`domains:write`	Đăng ký, gia hạn và quản lý tên miền
`domains:owner`	Lấy mã chuyển tên miền (EPP) và đổi chủ thể tên miền; bắt buộc giới hạn IP
`domains:registrant`	Xem và hoàn tất hồ sơ chủ thể tên miền đang chờ đăng ký (có CCCD, ngày sinh); bắt buộc giới hạn IP
`dns:read`	Xem bản ghi DNS
`dns:write`	Sửa bản ghi DNS
`billing:read`	Xem hoá đơn và thanh toán
`billing:write`	Thanh toán, nạp tiền
`orders:write`	Đặt mua dịch vụ: giỏ hàng, báo giá, tạo đơn (trả bằng số dư cần thêm quyền Thanh toán)
`tickets:read`	Xem ticket hỗ trợ
`tickets:write`	Tạo và trả lời ticket
`tinopay:read`	Xem TinoPay: tài khoản nhận tiền, giao dịch, webhook
`tinopay:write`	Quản lý TinoPay: tài khoản ảo, webhook, thông báo, tích hợp Sapo
`tinopay:owner`	Tạo API token TinoPay và liên kết tài khoản ngân hàng nhận tiền; bắt buộc giới hạn IP
`builder:read`	Xem website TinoPage Builder
`builder:write`	Quản lý website TinoPage Builder: tạo, đăng, tên miền riêng
`waf:read`	Xem website được TinoWAF bảo vệ và nhật ký sự kiện
`waf:write`	Quản lý TinoWAF: website, mức bảo vệ, máy chủ gốc, luật IP

Mỗi quyền mở một nhóm route; xem route của từng quyền ở Gọi API Tino.

`domains:owner` và giới hạn IP

domains:owner mở lấy mã EPP (GET /v1/domain/@id/epp), đổi liên hệ, chủ thể tên miền (PUT /v1/domain/@id/contact) Bốn route hồ sơ chủ thể của tên miền đang chờ có quyền riêng domains:registrant, cũng chỉ token cá nhân có giới hạn IP. Ai có hai route của domains:owner có thể chuyển tên miền đi nơi khác, nên token mang domains:owner bắt buộc khai danh sách IP: Tino từ chối tạo token khi danh sách trống. Token lộ ra ngoài cũng không chuyển được tên miền từ máy khác.

Gọi từ IP ngoài danh sách, mọi route của token đều trả 403 ip_not_allowed.

Gọi API

curl https://api.tino.vn/v1/domain -H "Authorization: Bearer tinopat_…"

Token gọi API như chính tài khoản đã tạo nó, chỉ trong các quyền đã chọn. Body, tham số và câu trả lời của từng route xem ở API Reference.

Giữ token như mật khẩu: để trong biến môi trường hoặc kho bí mật của server, không đưa vào mã nguồn, URL hay trình duyệt.

Theo dõi và thu hồi

Danh sách token ở https://auth.tino.vn/me/security hiện tên, quyền, IP được gọi, lúc tạo, lần dùng gần nhất (cập nhật tối đa mỗi phút một lần) và hạn dùng. Token hết hạn hiện nhãn Hết hạn.

Bấm Thu hồi để xoá token: phần mềm đang dùng nó nhận 401 invalid_token ngay ở lần gọi sau. Muốn đổi quyền, hạn dùng hay IP, tạo token mới rồi thu hồi token cũ.

Lỗi

HTTP	`error`	Nguyên nhân	Xử lý
401	`invalid_token`	token sai, hết hạn hoặc đã thu hồi	tạo token mới
403	`ip_not_allowed`	gọi từ IP ngoài danh sách giới hạn của token	gọi từ IP đã khai, hoặc tạo token với danh sách IP mới
403	`insufficient_scope`	token không có quyền của route	tạo token có thêm quyền
403	`ipnotallowed`	IP gọi API đang bị Tino chặn	liên hệ Tino

Khi tạo token, Tino báo lỗi nếu tên trống hoặc quá 64 ký tự, không chọn quyền nào, hạn dùng không hợp lệ, có IP hay dải IP sai (hoặc quá 20), chọn domains:owner mà không khai IP, hoặc đã đủ 20 token.