Đăng nhập
Đăng nhập SePay CLI trên máy của bạn bằng tài khoản my.sepay.vn:
$ sepay loginOpen your browser to authenticate. Your code: WDJB-MJHTOpening https://my.sepay.vn/...✓ Logged in as dev@congty.vnadd another account with: sepay login --profile <name>CLI in mã thiết bị và mở trang Kết nối thiết bị trên my.sepay.vn. Nhập mã vào trang rồi bấm Tiếp tục. Dòng ✓ Logged in as hiện ra khi đăng nhập xong.
Trong lúc chờ bạn duyệt, terminal hiện dòng phím tắt:
c copy link · y copy code · enter open browser · ctrl+c cancel⠙ waiting for approval…| Phím | Tác dụng |
|---|---|
c | Sao chép link trang Kết nối thiết bị. |
y | Sao chép mã thiết bị. |
Enter | Mở lại trình duyệt, chẳng hạn khi lỡ đóng tab. Không có trên máy không mở được trình duyệt. |
Ctrl+C hoặc Esc | Hủy đăng nhập. |
Khi chạy trong script (không có terminal), CLI chỉ in mã và link rồi chờ.

Ngôn ngữ màn hình đăng nhập
Màn hình đăng nhập hiện tiếng Việt khi máy đặt locale tiếng Việt: biến đầu tiên có giá trị trong LC_ALL, LC_MESSAGES, LANG bắt đầu bằng vi (trên Windows là ngôn ngữ hiển thị). Locale khác thì hiện tiếng Anh. Chọn hẳn một ngôn ngữ bằng SEPAY_LANG=vi hoặc SEPAY_LANG=en:
$ SEPAY_LANG=vi sepay loginMở trình duyệt để xác thực. Mã của bạn: WDJB-MJHTĐang mở https://my.sepay.vn/...c sao chép link · y sao chép mã · enter mở trình duyệt · ctrl+c huỷ⠙ đang chờ duyệt…Chỉ màn hình đăng nhập đổi ngôn ngữ. --help, các lệnh khác và output --json, -o yaml vẫn là tiếng Anh.
Tham số
| Flag | Kiểu | Mô tả |
|---|---|---|
--profile | string | Tên profile (mặc định là email tài khoản; không lấy được email, thường gặp với --with-token, thì là default). |
--scopes | string | Scope production được tích sẵn trên màn hình cấp quyền, ngăn cách bằng dấu phẩy. Mặc định: mọi scope. |
--with-token | bool | Nhận refresh token qua stdin, không mở trình duyệt. |
--insecure-storage | bool | Lưu token trong tệp 0600 thay vì keychain. |
Đăng nhập trên máy không có trình duyệt
Trên server hay qua SSH, sepay login không mở trình duyệt mà in link xác thực và mã thiết bị. Bấm c để sao chép link, y để sao chép mã, rồi mở link trên máy của bạn và nhập mã. CLI trên server nhận phiên đăng nhập ngay sau khi bạn duyệt.
$ sepay loginOpen your browser to authenticate. Your code: XXXX-XXXXVisit: https://my.sepay.vn/oauth/device/activatec copy link · y copy code · ctrl+c cancel⠙ waiting for approval…Phím sao chép ghi vào clipboard qua terminal (chuẩn OSC 52), nên khi SSH vào server, link và mã vẫn vào clipboard trên máy bạn. Trong tmux, bật set -g set-clipboard on hoặc set -g allow-passthrough on. Terminal chặn OSC 52 thì clipboard không đổi; khi đó chép tay link và mã.
Chuyển phiên sang máy khác
Nếu đã đăng nhập trên máy của bạn, chuyển luôn phiên đó sang máy đích thay vì đăng nhập lại:
$ sepay auth token | ssh dev-server "sepay login --with-token --profile dev-server"Chuyển ngay sau khi in: giá trị sepay auth token in ra chỉ dùng được một lần, và hết hiệu lực khi CLI làm mới phiên. Sau khi máy đích nhận phiên, máy nguồn có thể phải đăng nhập lại.
sepay auth token in refresh token ra stdout. Đừng chạy lệnh này ở nơi log được lưu lại (như bước build của CI), và đừng lưu kết quả vào biến môi trường hay secret để dùng lại nhiều lần.
Lưu trữ token
Token nằm trong keychain của hệ điều hành. Trên máy không dùng được keychain (máy chủ, container), sepay login tự lưu token vào tệp hosts.yml (quyền 0600) ở thư mục cấu hình và in cảnh báo:
! this computer has no password store sepay can use (OS keychain), so your login was savedin a file only your user account can read: /home/user/.config/sepay/hosts.ymlnothing else to do; on a shared computer, run sepay logout when you are doneMuốn lưu vào tệp ngay từ đầu thì đăng nhập với --insecure-storage.
Profile đang lưu trong keychain mà keychain từ chối ghi lúc CLI làm mới token giữa chừng thì CLI không chuyển sang tệp: lệnh vẫn chạy xong và in the renewed token is used for this run only and was not saved; lần chạy sau có thể phải đăng nhập lại.
Dùng máy chung thì chạy sepay logout khi xong việc để xóa token.
Profile
CLI lưu mỗi lần đăng nhập vào một profile, đặt tên theo email hoặc theo --profile. Profile gồm email, máy chủ, scope và token. Một máy giữ được nhiều profile cùng lúc, chẳng hạn một cho bạn và một riêng cho agent. Profile vừa đăng nhập trở thành profile mặc định cho các lệnh sau.
Xem các profile và tình trạng phiên của từng profile:
$ sepay auth statusCột SESSION cho biết phiên còn dùng được không: ok, expired, renews on next use, expired, run: sepay login, revoked, run: sepay login hoặc unknown. Profile mặc định có dấu *.
Thêm --active để chỉ xem profile mặc định. sepay auth status chỉ đọc thông tin lưu trên máy, không hỏi SePay. Vì vậy phiên bị thu hồi từ máy khác vẫn hiện ok cho tới khi một lệnh bị từ chối; lúc đó CLI tự gia hạn token, hoặc đánh dấu revoked, run: sepay login nếu phiên đã bị thu hồi.
Đổi profile mặc định cho các lệnh sau bằng sepay auth switch <tên>; bỏ trống tên thì CLI hiện danh sách để chọn.
$ sepay auth switch agent✓ Switched to profile agentChỉ một lệnh cần profile khác thì thêm --profile <tên>, ví dụ sepay transaction list --profile dev@congty.vn. Biến môi trường SEPAY_PROFILE có tác dụng như --profile cho mọi lệnh trong phiên shell đó.
Scope
Trên sandbox, lệnh không kiểm tra scope. Trên production, lệnh cần đúng scope của nó, ví dụ bank-account update cần bank-account:write. Các scope gồm: read, webhook:write, bank-account:write, paycode:write.
sepay login không kèm --scopes thì màn hình cấp quyền tích sẵn mọi scope production. Bỏ tích các scope không cần, hoặc dùng --scopes để chỉ tích sẵn những scope đó. Token không có scope production nào chỉ dùng được trên sandbox. Riêng --with-token không kèm --scopes thì giữ nguyên scope của phiên nguồn.
Thu hẹp scope
Để bỏ bớt scope mà không đăng nhập lại, chạy sepay auth refresh. Ví dụ bỏ quyền sửa mã thanh toán:
$ sepay auth refresh --remove-scopes paycode:write| Flag | Mô tả |
|---|---|
--scopes | Scope cần có, ngăn cách bằng dấu phẩy. Thêm vào tập hiện tại, hoặc thay hẳn tập đó khi có --reset-scopes. |
--remove-scopes | Scope cần bỏ, ngăn cách bằng dấu phẩy. |
--reset-scopes | Bỏ qua scope hiện tại, chỉ giữ các scope trong --scopes. |
auth refresh chỉ thu hẹp được: không vượt quá các scope đã cấp lúc đăng nhập, không lấy lại scope đã bỏ, và không bỏ được hết mọi scope. Cần thêm scope thì đăng nhập lại.
Thêm scope
Thiếu scope thì lệnh trả exit code 5. Đăng nhập lại và cấp đủ mọi scope cần dùng, kể cả các scope đang có (sepay auth status liệt kê ở cột SCOPES):
$ sepay login --scopes read,webhook:write,bank-account:writePhiên đăng nhập
Mỗi lần đăng nhập tạo một phiên mới. Xem các phiên đang có của tài khoản:
$ sepay auth sessionsThu hồi phiên đang dùng trên máy này và xóa thông tin đăng nhập đã lưu:
$ sepay logoutThu hồi một phiên theo ID mà sepay auth sessions liệt kê, chẳng hạn phiên của máy CI đã lộ token:
$ sepay auth revoke --token <id>Thu hồi tất cả phiên của tài khoản, trên mọi máy:
$ sepay auth revoke --allsepay auth revoke không kèm flag thu hồi phiên của profile đang dùng. Khác với sepay logout, profile vẫn còn trên máy và hiện revoked, run: sepay login trong sepay auth status cho tới khi bạn đăng nhập lại.
sepay auth revoke --all và sepay logout --all ảnh hưởng mọi máy nên hỏi xác nhận trước khi chạy. Không có terminal tương tác thì hai lệnh này dừng với exit code 2, trừ khi thêm --yes. Các lệnh còn lại trong mục này chạy ngay, không hỏi.
Phiên bị thu hồi mất hiệu lực trong khoảng 30 giây và không khôi phục được; máy dùng phiên đó phải đăng nhập lại.
Khi không kết nối được SePay để thu hồi, sepay logout giữ nguyên thông tin đăng nhập trên máy và trả exit code khác 0, để bạn chạy lại sau. sepay logout --local chỉ xóa trên máy này mà không gọi SePay; phiên vẫn dùng được tới khi hết hạn hoặc bị thu hồi bằng sepay auth revoke --all từ một máy khác.
So sánh token CLI và API Token
Token từ sepay login chỉ dùng cho CLI, có quyền trong phạm vi scope đã cấp và hết hạn nhanh, nhưng bạn không phải đăng nhập lại mỗi lần token hết hạn. API Token tạo trên my.sepay.vn có toàn quyền trên công ty và dùng được đến khi bị thu hồi. Hai loại không dùng thay cho nhau được.