Xác thực

Hai cách xác thực với API s.id, API key cho máy chủ tới máy chủ, OAuth 2.0 để hoạt động thay mặt người dùng.

Truy cập máy chủ đến máy chủ

API key xác thực các tích hợp máy chủ tới máy chủ. Tạo một cái tại Dashboard → Developer → API Keys, chọn phạm vi của bạn và truyền nó dưới dạng Bearer token.

Phạm vi	Quyền truy cập
`links:read`	Liệt kê và đọc liên kết
`links:write`	Tạo và cập nhật liên kết (tạo, sửa, khôi phục)
`links:archive`	Lưu trữ liên kết
`links:analytics`	Đọc thống kê lượt nhấp và tổng lượt nhấp trọn đời của từng liên kết
`qr:read`	Đọc cài đặt mã QR (toàn cục và theo từng liên kết)
`qr:write`	Tùy chỉnh cài đặt mã QR (toàn cục và theo từng liên kết)
`user:read`	Đọc hồ sơ người dùng đã xác thực và hạn mức tài khoản
`microsites:read`	Đọc microsite
`microsites:write`	Tạo, cập nhật và quản lý thành phần microsite
`microsites:delete`	Xóa microsite và các thành phần

bash

Authorization: Bearer sk_live_...

bash

curl https://api.s.id/v2/links \
  -H "Authorization: Bearer sk_live_..."

Key bắt đầu bằng sk_live_ và chỉ hiển thị một lần khi tạo.
Chỉ yêu cầu phạm vi tối thiểu mà tích hợp của bạn cần.
Thu hồi key ngay lập tức nếu bị xâm phạm, tạo cái mới.
Không bao giờ để lộ API key phía client (trình duyệt, ứng dụng mobile).

Luồng ủy quyền

Chuyển người dùng đến s.id để đồng ý, xác minh state của callback, rồi đổi mã dùng một lần lấy access token và refresh token xoay vòng.

Tạo giá trị state không thể đoán trước, lưu trong phiên người dùng và xác minh khớp chính xác khi callback để ngăn CSRF.
Sử dụng redirect_uri khớp chính xác với giá trị đã đăng ký cho ứng dụng OAuth của bạn.

Bắt buộc PKCE, không dùng client secret

Dành cho SPA, ứng dụng di động và CLI. Tạo code_verifier ngẫu nhiên, gửi challenge S256 khi ủy quyền, rồi gửi verifier gốc khi đổi token.

bash

https://api.s.id/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&
  scope=links%3Aread%20links%3Awrite&
  state=RANDOM_CSRF_VALUE&
  code_challenge=BASE64URL_SHA256_VERIFIER&
  code_challenge_method=S256

bash

curl -X POST https://api.s.id/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "code_verifier=ORIGINAL_RANDOM_VERIFIER"

Client secret trên backend đáng tin cậy

Dành cho ứng dụng render phía máy chủ hoặc backend có thể giữ bí mật client_secret. PKCE vẫn là tùy chọn và được khuyến nghị như một lớp bảo vệ bổ sung.

bash

https://api.s.id/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&
  scope=links%3Aread%20links%3Awrite&
  state=RANDOM_CSRF_VALUE

bash

curl -X POST https://api.s.id/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback"

Token truy cập	Mô tả
`access_token`	Hết hạn sau 1 giờ
`refresh_token`	Hết hạn sau 30 ngày
`code`	Chỉ dùng một lần; hết hạn sau 10 phút

bash

curl -X POST https://api.s.id/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "refresh_token=CURRENT_REFRESH_TOKEN"

bash

curl -X POST https://api.s.id/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_TO_REVOKE"}'

Khám phá và thao tác token	Mô tả
`https://api.s.id/.well-known/oauth-authorization-server`	Khám phá URL endpoint, phạm vi được hỗ trợ và phương thức PKCE qua siêu dữ liệu RFC 8414.
`POST /oauth/introspect`	Máy chủ tài nguyên bảo mật có thể kiểm tra token còn hoạt động và xem các phạm vi của token.
`POST /oauth/revoke`	Thu hồi access token hoặc refresh token khi người dùng ngắt kết nối tích hợp của bạn.
`GET /oauth/userinfo`	Đọc hồ sơ liên kết với token truy cập OAuth mang phạm vi user:read.

Mở Bảng điều khiển nhà phát triển