Hans API

Appearance

토큰 ​

OAuth 2.0 토큰 엔드포인트입니다. 인가코드를 토큰으로 바꾸고, 만료 전에 갱신합니다.

흐름 전체는 공통 › 로그인 연동 에 있습니다 — 이 페이지는 그 흐름에서 호출하는 엔드포인트의 요청·응답 스키마입니다.

  • Authorization Code + PKCE 만 지원합니다(code_challenge_method=S256).
  • 공개 클라이언트라 client secret 이 없습니다.
  • refresh token 은 1회용입니다. 갱신하면 새 값으로 교체되고 직전 값은 무효가 됩니다.

엔드포인트 주소는 discovery 에서 읽으세요

GET /.well-known/openid-configuration 에 token_endpoint · authorization_endpoint · jwks_uri 가 실려 있습니다. URL 을 코드에 박지 마세요.

인가 코드 발급​

POST
/oauth/authorize

OAuth 2.0 Authorization Code Grant 의 인가 코드(authorization code)를 발급한다. 로그인된 사용자에 대해, 클라이언트가 등록한 redirect_uri 로 전달할 1회용 코드다.

발급된 코드는 POST /oauth/token 에서 access token 으로 교환한다.

Request

🔒 Bearer 인증 필요 · 인증 방법
POST/oauth/authorize

Request Body

application/jsonrequired

AuthorizeRequest

FieldTypeRequiredConstraintsDescription
redirectUristringrequiredOAuth2 redirect_uri — 코드를 실어 돌려보낼 클라이언트 URL. clientId 를 주면 그 클라이언트에 등록된 리디렉션 URI 와 정확히 일치해야 하고, 없으면 1st-party 허용목록 오리진이어야 한다.
clientIdstringoptional외부 앱의 공개 클라이언트 ID. 생략하면 1st-party(인증웹 자신)로 간주한다. 이 값은 발급되는 코드에 기록되어, 토큰 교환 때 요청 Origin 대조의 기준이 된다.
codeChallengestringrequiredPKCE code_challenge = BASE64URL(SHA256(code_verifier)), 43자. S256 만 받는다. 발급되는 코드에 기록되어 교환 때 code_verifier 와 대조된다.
{
  "redirectUri": "https://medifinder.kr/auth/callback",
  "clientId": "cl_fixed_medifinder",
  "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
}

Response

200

AuthorizeResponse

FieldTypeRequiredConstraintsDescription
codestringrequired1회용 인가코드(ac_...)
{
  "code": "string"
}

Playground​

Server
Authorization
Body

Samples​

Powered by VitePress OpenAPI

토큰 발급/갱신​

POST
/oauth/token

grant_type=authorization_code 는 인가코드(code)를 토큰으로 교환한다. 코드에 기록된 클라이언트의 등록 오리진과 요청 Origin 이 일치해야 한다.

grant_type=refresh_token 은 refresh token(바디 또는 httpOnly 쿠키)을 갱신한다. refresh token 은 1회용이다 — 갱신에 성공하면 새 refresh token 이 나오고 직전 것은 그 즉시 무효가 된다(rotate). 응답으로 받은 새 값으로 반드시 교체해 두고, 이전 값을 다시 보내면 거부된다. 같은 토큰으로 두 번 갱신하거나, 갱신 응답을 저장하지 못한 채 재시도하면 세션이 끊어진다.

Request

POST/oauth/token

Request Body

application/jsonrequired

TokenRequest

FieldTypeRequiredConstraintsDescription
grant_typestringrequiredauthorization_code, refresh_tokengrant 종류
codestringoptionalauthorization_code grant 의 인가코드(ac_...)
refresh_tokenstringoptionalrefresh_token grant 의 refresh token(rt_...). 생략 시 httpOnly 쿠키에서 읽는다.
code_verifierstringoptionalPKCE code_verifier(RFC 7636). authorization_code grant 에 **필수**다. 인가 요청 때 보낸 code_challenge 의 원본으로, BASE64URL(SHA256(이 값)) 이 일치해야 한다.
{
  "grant_type": "authorization_code",
  "code": "string",
  "refresh_token": "string",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

Response

200

TokenResponse

FieldTypeRequiredConstraintsDescription
accessTokenstringrequiredaccess token(JWT)
tokenTypestringrequired토큰 타입
expiresInnumberrequiredaccess token 만료(초)
refreshTokenstringrequiredrefresh token(불투명, rt_...). **1회용이다** — 이 값으로 갱신하면 새 refresh token 이 발급되고 이 값은 그 즉시 무효가 된다. 응답을 받으면 반드시 새 값으로 교체해 보관할 것.
refreshExpiresAtstringrequiredrefresh token 만료 시각(ISO8601)
{
  "accessToken": "string",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "refreshToken": "string",
  "refreshExpiresAt": "2026-09-20T12:00:00.000Z"
}

Playground​

Server
Body

Samples​

Powered by VitePress OpenAPI

공개키셋(JWKS)​

GET
/.well-known/jwks.json

access token 서명 검증에 쓰는 공개키를 반환한다. 토큰 헤더의 kid 로 키를 고른다.

키를 교체해도 퇴역한 키의 공개키가 남아 있어, 이미 발급된 토큰은 만료될 때까지 검증된다. 주소는 discovery 문서의 jwks_uri 로 알아내는 것을 권장한다.

Request

GET/.well-known/jwks.json

Response

200

Jwks

FieldTypeRequiredConstraintsDescription
keysJsonWebKey[]required공개키 목록

JsonWebKey

FieldTypeRequiredConstraintsDescription
ktystringrequired키 종류
crvstringoptional곡선 이름(EC 키)
xstringoptional공개키 x 좌표(base64url)
ystringoptional공개키 y 좌표(base64url)
kidstringoptional키 식별자. 토큰 헤더의 `kid` 와 대조해 검증 키를 고른다.
algstringoptional서명 알고리즘
usestringoptional키 용도
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "string",
      "y": "string",
      "kid": "iE5LAAsM8p-NGSKO",
      "alg": "ES256",
      "use": "sig"
    }
  ]
}

Playground​

Samples​

Powered by VitePress OpenAPI

Discovery 문서​

GET
/.well-known/openid-configuration

로그인·토큰 발급·공개키 주소를 한 번에 알려준다(RFC 8414 / OpenID Connect Discovery). 표준 클라이언트 라이브러리는 이 주소만으로 연동을 마칠 수 있다.

지원하는 흐름은 authorization code + PKCE(S256) 이며, 모든 인가 코드에 PKCE 를 요구한다.

Request

GET/.well-known/openid-configuration

Response

200

OpenIdConfiguration

FieldTypeRequiredConstraintsDescription
issuerstringoptional발급자 식별자. access token 의 `iss` 클레임과 같다.
authorization_endpointstringoptional로그인 화면 주소. 인가 요청을 이리로 보낸다.
token_endpointstringoptional토큰 발급·갱신 주소.
jwks_uristringoptionalaccess token 서명 검증용 공개키셋(JWKS) 주소.
grant_types_supportedstring[]required지원하는 grant type.
response_types_supportedstring[]required지원하는 response type.
code_challenge_methods_supportedstring[]required지원하는 PKCE 코드 챌린지 방식. 모든 인가 코드에 PKCE 를 요구한다.
token_endpoint_auth_methods_supportedstring[]required토큰 엔드포인트의 클라이언트 인증 방식. 공개 클라이언트라 `none` 이다.
id_token_signing_alg_values_supportedstring[]required토큰 서명 알고리즘. 대칭 폴백 모드에서는 빈 배열이다.
subject_types_supportedstring[]required지원하는 subject 식별자 유형.
{
  "issuer": "https://api.plzhans.com",
  "authorization_endpoint": "https://auth.plzhans.com/login",
  "token_endpoint": "https://api.plzhans.com/oauth/token",
  "jwks_uri": "https://api.plzhans.com/.well-known/jwks.json",
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types_supported": [
    "code"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint_auth_methods_supported": [
    "none"
  ],
  "id_token_signing_alg_values_supported": [
    "ES256"
  ],
  "subject_types_supported": [
    "public"
  ]
}

Playground​

Samples​

Powered by VitePress OpenAPI