Chuyển tới nội dung
Sursa Developers

POST/oauth/token

Cấp token OAuth 2.0

oauth_token

Endpoint cấp token OAuth 2.0 (RFC 6749, mục 3.2). grant_type: authorization_code đổi một mã dùng một lần lấy cặp token và cần code_verifier (PKCE S256); refresh_token cấp cặp mới cho token làm mới và vô hiệu hóa token làm mới trước (xoay vòng), còn dùng lại token đã bị vô hiệu hóa sẽ thu hồi toàn bộ chuỗi; client_credentials cấp token thay mặt tổ chức, chỉ cho ứng dụng confidential, không có token làm mới. Client confidential xác thực bằng header Authorization: Basic hoặc bằng các trường client_id và client_secret; client công khai chỉ gửi client_id. Token truy cập có hiệu lực 1 giờ, token làm mới có hiệu lực 90 ngày. Phản hồi và lỗi theo RFC 6749, mục 5, kèm Cache-Control: no-store. Được thêm trong 1.62.0.

Xác thực

Không cần thông tin xác thực.

Phần thân yêu cầu

application/x-www-form-urlencoded

Đối tượng: OAuthTokenRequest

  • grant_typestringbắt buộc

    Giá trị cho phép: authorization_coderefresh_tokenclient_credentials

  • codestring

    Mã ủy quyền (authorization_code).

  • redirect_uristring

    Cùng URI chuyển hướng như trong yêu cầu ủy quyền (authorization_code).

  • code_verifierstring

    Giá trị PKCE ban đầu, từ 43 đến 128 ký tự (authorization_code).

  • refresh_tokenstring

    Token làm mới (refresh_token).

  • scopestring

    Các phạm vi quyền cách nhau bằng dấu cách, chỉ để thu hẹp (refresh_token, client_credentials).

  • client_idstring

    ID của ứng dụng, khi khóa bí mật không được truyền trong header Authorization: Basic.

  • client_secretstring

    Khóa bí mật của client của ứng dụng confidential, khi nó không được truyền trong header Authorization: Basic.

Phản hồi

200Đã cấp token.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: OAuthTokenResponse

  • access_tokenstringbắt buộc

    Token truy cập (kbat_…) cho header Authorization: Bearer.

  • token_typestringbắt buộc

    Giá trị cho phép: Bearer

  • expires_inintegerbắt buộc

    Thời gian sống của token truy cập, tính bằng giây.

  • refresh_tokenstring

    Token làm mới (kbrt_…); không có với client credentials.

  • scopestringbắt buộc

    Các phạm vi quyền của token, cách nhau bằng dấu cách.

400Lỗi theo định nghĩa trong RFC 6749, mục 5.2.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: OAuthErrorResponse

401Thông tin xác thực của client không hợp lệ (`invalid_client`).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: OAuthErrorResponse

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lại yêu cầu.

Giới hạn tốc độ

Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.

← oauth · Tài liệu tham chiếu API