Tra cứu API
Đặc tả yêu cầu và phản hồi của mọi API Tài khoản 놀아, bao gồm cả các điểm cuối (endpoint) OAuth.
Đây là 4 điểm cuối (endpoint) mà Tài khoản 놀아 cung cấp. Mọi ví dụ đều viết theo máy chủ này (https://account.nola.kr).
GET /oauth/authorize
Đưa người dùng tới màn hình đăng nhập và đồng ý. Đây không phải API máy chủ mà là địa chỉ để chuyển hướng trình duyệt.
| Tham số | Bắt buộc | Giá trị |
|---|---|---|
response_type | Bắt buộc | Cố định là code |
client_id | Bắt buộc | Giá trị được cấp trong Tài khoản của tôi |
redirect_uri | Bắt buộc | Phải hoàn toàn trùng với callback URL đã đăng ký |
scope | Bắt buộc | Phân cách bằng dấu cách. Để trống sẽ báo invalid_scope |
state | Bắt buộc | Số ngẫu nhiên chống CSRF. Thiếu sẽ báo invalid_request |
code_challenge | Bắt buộc | PKCE. Thiếu sẽ báo pkce_required |
code_challenge_method | Khuyến nghị | Chỉ chấp nhận S256. Nếu bỏ qua thì coi như S256 |
ui_locales | Tùy chọn | Ngôn ngữ màn hình đăng nhập và đồng ý. ko, en, vi. Có thể ghi nhiều, cách nhau bằng dấu cách.Ngôn ngữ người dùng tự chọn được ưu tiên. Không ảnh hưởng đến xác thực |
Khi thành công, người dùng được đưa về callback URL kèm ?code=...&state=....
authorization code có hiệu lực 10 phút · chỉ dùng một lần.
POST /oauth/token
Gửi bằng application/x-www-form-urlencoded. Bắt buộc gọi từ máy chủ — vì có chứa client_secret.
Đổi authorization code
curl -X POST https://account.nola.kr/oauth/token \ -d "grant_type=authorization_code" \ -d "code=RECEIVED_CODE" \ -d "redirect_uri=YOUR_REDIRECT_URI" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "code_verifier=SAVED_VERIFIER"
Làm mới token
curl -X POST https://account.nola.kr/oauth/token \ -d "grant_type=refresh_token" \ -d "refresh_token=SAVED_REFRESH_TOKEN" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET"
Phản hồi (chung cho cả hai)
{
"access_token": "…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "…",
"scope": "profile.avatar profile.basic"
}
refresh_token mới trong phản hồi. Nếu tiếp tục dùng giá trị cũ, lần làm mới tiếp theo sẽ thất bại.| Thời hạn | Mặc định |
|---|---|
| access_token | 1 giờ (xem expires_in) |
| refresh_token | 30 ngày |
| authorization code | 10 phút · dùng một lần |
GET /oauth/userinfo
curl https://account.nola.kr/oauth/userinfo \ -H "Authorization: Bearer ACCESS_TOKEN"
{
"sub": "pws_xxxxxxxxxxxxxxxx",
"nickname": "놀아유저",
"scope": "profile.avatar profile.basic service.member_email.read",
"profile_image_url": "https://…/uploads/…jpg",
"email": "user@example.com"
}
profile_image_url chỉ có khi có profile.avatar, và là null nếu chưa có ảnh.
email chỉ có khi thỏa điều kiện trong Tra cứu scope.
sub khác nhau theo từng dịch vụ (định danh riêng theo dịch vụ, pairwise). Cùng một người nhưng ở dịch vụ khác sẽ nhận giá trị khác.
Có thể dùng làm khóa nhận diện người dùng, nhưng không dùng để đối chiếu giữa các dịch vụ.GET /oauth/domain-info
Chỉ dành cho scope service.domain.read. Trả về danh sách dịch vụ mà người dùng đã đăng ký.
curl https://account.nola.kr/oauth/domain-info \ -H "Authorization: Bearer ACCESS_TOKEN"
{
"sub": "pws_…",
"scope": "profile.basic service.domain.read",
"services": [
{ "name": "…", "description": "…", "domain": "https://…",
"status": "active", "created_at": "…", "verified_at": "…" }
]
}
Nếu thiếu scope, kết quả là 403 insufficient_scope.
Ngắt kết nối — không có điểm cuối công khai
Hiện tại Tài khoản 놀아 không có API công khai để thu hồi token (điểm cuối revoke). Nghĩa là phía dịch vụ không có cách nào xử lý «ngắt kết nối Tài khoản 놀아» bằng một lời gọi.
Vì vậy hãy xây dựng dịch vụ để khi nhận 401 invalid_token thì lặng lẽ đăng xuất người dùng.
Khi người dùng đã dọn dẹp kết nối ở phía Tài khoản 놀아 hoặc token đã hết hạn, đó là tín hiệu duy nhất mà dịch vụ nhận biết được.
Để đăng xuất khỏi chính dịch vụ, chỉ cần xóa phiên của dịch vụ. Không cần chấm dứt cả phiên Tài khoản 놀아.
Định dạng phản hồi lỗi
{ "error": "invalid_grant", "error_description": "pkce verification failed" }
error_description có thể không có. Danh sách đầy đủ có trong Từ điển mã lỗi.