<aside> 💡 헤이홈 API는 OAuth2.0 기반의 인가 방식을 사용하고 있습니다.

</aside>

헤이홈 API를 사용하려면 헤이홈 API를 사용할 수 있는 권한이 필요합니다. API 요청 시마다 액세스 토큰(Access Token)을 함께 보내주시면, 해당 토큰을 통해 권한을 체크합니다.

이 페이지는 액세스 토큰(Access Token) 및 리프레시 토큰(Refresh Token) 발급 과정을 설명합니다.

다음은 토큰 얻기 과정의 시퀀스 다이어그램 입니다.

Untitled

목차

인가 코드 획득

토큰 발급을 위해 필요한 ‘인가 코드'를 획득하는 API입니다.

해당 API를 요청하면, 헤이홈 로그인 화면이 호출됩니다.

Untitled

사용자가 헤이홈 ID/PW를 입력 후 LOGIN 버튼을 클릭하면 사용자 인증이 진행됩니다. 사용자 인증이 완료되면, API 요청 시 입력한 redirect_uri로 리다이렉트 됩니다. 이 때, 쿼리 스트링에 인가 코드(code) 값이 포함됩니다.

Request

GET /login/openapi
Host: goqual.io
Name Type Parameter Type 설명 Required
response_type String Query String 고정 값: code yes
client_id String Query String 발급 받은 client_id yes
scope String Query String 고정 값: openapi yes
redirect_uri String Query String 인가 코드가 리다이렉트 될 URI.
사용신청서에 작성했던 Redirect URI와 반드시 일치해야 합니다.
인코딩 없이 보내주셔야 합니다. yes

Response

html페이지에 Error Message를 담아 반환됩니다.

Sample

GET /login/openapi?response_type=code&client_id=l3ksdu8en2***c234ia&scope=openapi&redirect_uri=https://example-app.com/redirect
Host: goqual.io

성공 시, 다음의 URI로 리다이렉트됩니다.

<https://example-app.com/redirect?code=WIdIxz>

토큰 획득

발급 받은 인가 코드를 사용하여 액세스 토큰(Access Token) 및 리프레시 토큰(Refresh Token)을 발급받는 API입니다.

Request

POST /oauth/token
Host: goqual.io
Authorization: Basic ${Base64 encoded ClientId and ClientSecret}
Name Value 설명 Required
Authorization Basic ${Base64 encoded ClientId and ClientSecret} ClientId:ClientSecret을 Base64 인코딩한 값(ClientId와 ClientSecret은 :(콜론)으로 구분합니다) yes
Name Type Parameter Type 설명 Required
grant_type String Query String 고정 값: authorization_code yes
code String Query String 인가 코드 획득 API를 통해 발급 받은 code 값. 한 번 사용된 코드 값은 재사용 불가합니다. yes
redirect_uri String Query String 사용신청서에 작성했던 Redirect URI와 반드시 일치해야 합니다. yes

Response

Name Type 설명
access_token String 액세스 토큰 값, 유효기간은 180일입니다.
token_type String 토큰 타입, bearer로 고정 값
refresh_token String 리프레시 토큰 값, 유효기간은 360일입니다.
expires_in Integer 액세스 토큰 만료 시간(초)
scope String openapi로 고정 값

Sample

POST /oauth/token?grant_type=authorization_code&code=WIdIxz&redirect_uri=https://example-app.com/redirect
Host: goqual.io
Authorization: Basic Y2xpZW50SWQ6Y2***U2VjcmV0

{
    "access_token": "790af99-74b2-****-824a-d580c",
    "token_type": "bearer",
    "refresh_token": "9f93b55-4392-****-b9cd-d50c999",
    "expires_in": 10716651,
    "scope": "openapi"
}

토큰 갱신

액세스 토큰이 만료되었을 경우, 해당 API를 통해 액세스 토큰 및 리프레시 토큰을 재발급 받을 수 있습니다.

Request

POST oauth/token
Host: goqual.io
Authorization: Basic ${Base64 encoded ClientId and ClientSecret}
Content-Type: application/x-www-form-urlencoded
Name Value 설명 Required
Authorization Basic ${Base64 encoded ClientId and ClientSecret} ClientId:ClientSecret을 Base64 인코딩한 값(ClientId와 ClientSecret은 :(콜론)으로 구분합니다) yes
Content-Type application/x-www-form-urlencoded yes
Name Type Parameter Type 설명 Required
grant_type String Body 고정 값: refresh_token yes
refresh_token String Body 토큰 획득 API를 통해 발급 받은 refresh_token 값 yes

Response

Name Type 설명
access_token String 액세스 토큰 값
token_type String 토큰 타입, bearer로 고정 값
refresh_token String 리프레시 토큰 값
expires_in Integer 액세스 토큰 만료 시간(초)
scope String openapi로 고정 값

Sample

POST /oauth/token
Host: goqual.io
Authorization: Basic Y2xpZW50SWQ6Y2***U2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type: refresh_token
refresh_token: 9f93b550-4392-****-b9cd-d50c999

{
    "access_token": "78sdf21-0a77-****-bc95-9b13se",
    "token_type": "bearer",
    "refresh_token": "9f93b55-4392-****-b9cd-d507bf99",
    "expires_in": 15551999,
    "scope": "openapi"
}