T
Tick Up
Nhà phát triển
Đăng ký tài khoản
Bắt đầu

Xác thực

Tick Up dùng JWT access token ngắn hạn kèm refresh token xoay vòng. Cả đăng nhập bằng email + mật khẩu và Google OAuth đều tạo ra cùng một cặp token.

Cách hoạt động

Tick Up phát hành hai loại token:

  • Access token — JWT, thời hạn 24 giờ, gửi kèm mỗi request API dưới dạng bearer token trong header Authorization. Nó mang theo user ID, tenant ID và role của bạn.
  • Refresh token — token đục, thời hạn 7 ngày, được đổi lấy access token mới + refresh token mới khi access token sắp hết hạn. Refresh token xoay vòng nghĩa là một refresh token bị đánh cắp sẽ bị vô hiệu hóa ngay lần client hợp lệ thực hiện refresh tiếp theo.

Đăng nhập bằng email + mật khẩu

POST/api/v1/auth/loginCông khai

Đổi email + mật khẩu lấy access token + refresh token.

Body của request

TrườngKiểuMô tả
emailbắt buộcstringĐịa chỉ email của người dùng (không phân biệt hoa thường).
passwordbắt buộcstringMật khẩu dạng văn bản. Được băm bằng bcrypt phía server.
curl -X POST https://tickup-api.onrender.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@yourcompany.com",
    "password": "your-password"
  }'

Phản hồi:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Sử dụng access token

Mọi request có xác thực đều cần header Authorization:

http
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Gửi nó trong mỗi request — kể cả các request idempotent như GET /candidates. Token bị thiếu, sai định dạng, hoặc hết hạn sẽ trả về:

{ "detail": "Not authenticated" }

Khi nhận được 401 với Token expired, hãy refresh và thử lại request gốc một lần.

Refresh token

POST/api/v1/auth/refreshCông khai

Đổi refresh token lấy access token mới + refresh token đã xoay.

Refresh token xoay sau mỗi lần dùng. Refresh token mới thay thế cái bạn vừa dùng — hãy lưu lại và bỏ cái cũ đi.

curl -X POST https://tickup-api.onrender.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "eyJhbGciOiJIUzI1NiIs..." }'

Nếu refresh token đã hết hạn hoặc bị thu hồi, cuộc gọi trả về 401 Unauthorized. Đến lúc này, người dùng phải đăng nhập lại — không có cơ hội thứ hai.

Google OAuth

POST/api/v1/auth/googleCông khai

Đổi Google ID token lấy Tick Up access token + refresh token.

Nếu tích hợp của bạn chạy như một phần của sản phẩm mà người dùng đã đăng nhập bằng Google, bạn có thể bỏ qua hoàn toàn bước email + mật khẩu. Lấy ID token từ Google Sign-In phía client, rồi POST nó đến endpoint Google login.

shell
curl -X POST https://tickup-api.onrender.com/api/v1/auth/google \
  -H "Content-Type: application/json" \
  -d '{ "id_token": "eyJhbGciOiJSUzI1NiIs..." }'

Người dùng Google mới sẽ được cấp tenant + admin user mới. Người dùng cũ trở lại sẽ nhận access token cho chính tenant họ từng dùng. Nếu cần luồng mời theo lời mời (invite-only), xem /auth/invite trong tài liệu đầy đủ.

Đăng xuất

POST/api/v1/auth/logoutCần xác thực

Thu hồi refresh token được cung cấp. Access token tương ứng vẫn hoạt động đến khi hết hạn (tối đa 24 giờ).

Tick Up không duy trì blocklist cho access token — một khi đã phát hành, chúng còn hiệu lực đến khi hết hạn. Để đẩy người dùng ra ngay lập tức, hãy thu hồi refresh token và xóa các access token cache phía client.

Kiểm tra token hiện tại

GET/api/v1/auth/meCần xác thực

Trả về user, role và tenant gắn với access token hiện tại.

Dùng endpoint này khi app khởi động để xác nhận token đã lưu vẫn hoạt động, và để hiển thị tên + avatar của người dùng đang đăng nhập.

Khoá API cho máy

Cần một script, dashboard hay coding agent đọc dữ liệu định kỳ? Đừng dùng token đăng nhập ở trên — hãy tạo khoá API chỉ đọc (dạng tk_live_…) và gọi Data API. Khoá không gắn với phiên đăng nhập của ai và chỉ đọc được, nên an toàn hơn cho máy.

Pattern production

  • Refresh chủ động. Refresh access token ~60 giây trước khi hết hạn, không phải sau khi đã hết. Một lỗi 401 giữa request là trải nghiệm tệ hơn nhiều so với một lần refresh nền âm thầm.
  • Tập trung logic refresh. Bao gói HTTP client của bạn để mỗi lỗi 401 với Token expired kích hoạt đúng một lần refresh, rồi thử lại request gốc. Tránh đồng loạt bằng cách xếp các cuộc gọi đồng thời sau promise refresh.
  • Giữ refresh token phía server. Nếu đang xây tích hợp server-to-server, điều này tự nhiên đã có. Nếu đang xây frontend trình duyệt, dùng cookie HTTP-only được hỗ trợ bởi server của bạn — đừng bao giờ dùng localStorage.
  • Xoay khi nghi ngờ. Nếu nghi ngờ một token bị lộ, gọi POST /auth/logout với refresh token đó và buộc đăng nhập lại.
    Xác thực | Tick Up Developers