본문으로 건너뛰기
Sursa Developers

POST/oauth/token

OAuth 2.0 토큰 발급

oauth_token

OAuth 2.0 토큰 엔드포인트(RFC 6749, 3.2절). grant_type 값: authorization_code는 일회용 코드를 토큰 쌍으로 교환하며 code_verifier 값(PKCE S256)이 필요해요. refresh_token은 리프레시 토큰으로 새 토큰 쌍을 발급하고 이전 리프레시 토큰을 무효화하며(교체), 무효화된 토큰을 다시 쓰면 체인 전체가 폐기돼요. client_credentials는 confidential 앱에서만 쓸 수 있으며, 리프레시 토큰 없이 조직을 대신하는 토큰을 발급해요. confidential 클라이언트는 Authorization: Basic 헤더나 client_id, client_secret 필드로 인증하고, 공개 클라이언트는 client_id 값만 보내요. 액세스 토큰은 1시간, 리프레시 토큰은 90일 동안 유효해요. 응답과 오류는 RFC 6749 5절을 따르며 Cache-Control: no-store 헤더가 붙어요. 1.62.0에서 추가됐어요.

인증

자격 증명이 필요 없어요.

요청 본문

application/x-www-form-urlencoded

객체: OAuthTokenRequest

  • grant_typestring필수

    허용 값: authorization_coderefresh_tokenclient_credentials

  • codestring

    인가 코드(authorization_code).

  • redirect_uristring

    인가 요청과 같은 리다이렉트 URI(authorization_code).

  • code_verifierstring

    원래 PKCE 값, 43~128자(authorization_code).

  • refresh_tokenstring

    리프레시 토큰(refresh_token).

  • scopestring

    공백으로 구분한 스코프로, 좁히는 것만 가능해요(refresh_token, client_credentials).

  • client_idstring

    Authorization: Basic 헤더로 시크릿을 전달하지 않을 때의 앱 ID.

  • client_secretstring

    Authorization: Basic 헤더로 전달하지 않을 때의 confidential 앱 클라이언트 시크릿.

응답

200토큰이 발급되었어요.

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: OAuthTokenResponse

  • access_tokenstring필수

    Authorization: Bearer 헤더에 넣는 액세스 토큰(kbat_…).

  • token_typestring필수

    허용 값: Bearer

  • expires_ininteger필수

    액세스 토큰의 유효 기간(초).

  • refresh_tokenstring

    리프레시 토큰(kbrt_…). 클라이언트 자격 증명에는 없어요.

  • scopestring필수

    공백으로 구분한 토큰의 스코프.

400RFC 6749 5.2절에 정의된 오류.

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: OAuthErrorResponse

401잘못된 클라이언트 자격 증명(`invalid_client`).

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: OAuthErrorResponse

안전한 재시도

POST와 PATCH 요청마다 Idempotency-Key 헤더(예: UUID)를 보내세요. 24시간 안에 같은 키로 재시도하면 요청을 다시 실행하지 않고 저장된 응답을 반환해요.

호출 한도

응답에는 RateLimit, RateLimit-Policy 헤더와 이전 헤더인 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 담겨요. 429 응답에는 초 단위의 Retry-After 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.

← oauth · API 레퍼런스