<aside> 💡 헤이홈 API는 OAuth2.0 기반의 인가 방식을 사용하고 있습니다.
</aside>
헤이홈 API를 사용하려면 헤이홈 API를 사용할 수 있는 권한이 필요합니다. API 요청 시마다 액세스 토큰(Access Token)을 함께 보내주시면, 해당 토큰을 통해 권한을 체크합니다.
이 페이지는 액세스 토큰(Access Token) 및 리프레시 토큰(Refresh Token) 발급 과정을 설명합니다.
다음은 토큰 얻기 과정의 시퀀스 다이어그램 입니다.
토큰 발급을 위해 필요한 ‘인가 코드'를 획득하는 API입니다.
해당 API를 요청하면, 헤이홈 로그인 화면이 호출됩니다.
사용자가 헤이홈 ID/PW를 입력 후 LOGIN 버튼을 클릭하면 사용자 인증이 진행됩니다. 사용자 인증이 완료되면, API 요청 시 입력한 redirect_uri로 리다이렉트 됩니다. 이 때, 쿼리 스트링에 인가 코드(code) 값이 포함됩니다.
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 |
성공 시
${redirect_uri}?code=${code}⇒ 그 결과 ${redirect_uri}?code=${code}로 리다이렉트됩니다.
실패 시
html페이지에 Error Message를 담아 반환됩니다.
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입니다.
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 |
| Name | Type | 설명 |
|---|---|---|
| access_token | String | 액세스 토큰 값, 유효기간은 180일입니다. |
| token_type | String | 토큰 타입, bearer로 고정 값 |
| refresh_token | String | 리프레시 토큰 값, 유효기간은 360일입니다. |
| expires_in | Integer | 액세스 토큰 만료 시간(초) |
| scope | String | openapi로 고정 값 |
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를 통해 액세스 토큰 및 리프레시 토큰을 재발급 받을 수 있습니다.
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 |
| Name | Type | 설명 |
|---|---|---|
| access_token | String | 액세스 토큰 값 |
| token_type | String | 토큰 타입, bearer로 고정 값 |
| refresh_token | String | 리프레시 토큰 값 |
| expires_in | Integer | 액세스 토큰 만료 시간(초) |
| scope | String | openapi로 고정 값 |
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"
}