> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/tools/billing/v21/web-payment/member.md). # 회원 인증 ## 1.개요 Windows 앱을 EXE 유형으로 서비스 하는 경우 웹 결제 규격을 연동해야 합니다.\ 웹 결제 규격 연동 시 회원 인증(로그인)이 필요하므로 이 규격서를 제공합니다. * 결제 서버 API는 회원 인증(로그인) 시 제공되는 OAuth Token(이하 User Access Token)을 이용합니다. * 결제 시마다 회원 인증(로그인)을 수행하지 않도록 OAuth 인증을 지원합니다. ## 2.주의사항 Embedded Browser(웹뷰)에서 구글 SDK를 적용하지 않고, 구글 Oauth 로그인을 시도하는 경우 403 에러가 발생합니다. \ 아래의 방법을 통해 403 에러를 방지할 수 있습니다. * Embedded Browser가 아닌 새 창으로 로그인을 시도합니다. * UserAgent 정보를 수정하여 Embedded Browser가 아닌 웹으로 인식하도록 처리합니다. ## 3.회원 인증 플로우 ### 3.1 Conceptual View

### 3.2 논리 API ↔ 물리 API 규격 매핑 Conceptual View'에 표기된 논리 API들이 매핑되는 물리 API 규격은 다음과 같습니다.

No	Flow	논리 API	물리 API (연동 규격)
1	회원인증	Loging UI 요청	4.2 ONE store 로그인 인증 요청
2	회원인증	ONEstore UserAccessToken 발급	4.3 ONE store User Access Token 발급 요청

## 4. ONE store 회원인증 ### 4.1 ONE store 로그인 API 개요 ONE store 로그인 API는 아래와 같이 구성되어 있습니다. * ONE store 로그인 인증 요청 API * 접근 토큰(User Access Token) 발급/삭제 요청 API ONE store 로그인 인증 요청 API는 개발자 서비스 Web에 ONE store 로그인 화면을 띄우는 API입니다. 사용자가 ONE store 회원 인증에 성공하면 API로부터 받은 임시코드(code) 값을 이용해서 접근 토큰(User Access Token) 발급 요청 API를 호출합니다. 접근 토큰 발급 요청 API를 통해 받은 접근 토큰은 여러가지 Server API들을 호출하는데 사용합니다. 접근 토큰(User Access Token)은 갱신 토큰(Refresh Token)에 비하여 만료기한이 짧으며, 접근 토큰 만료 시 갱신 토큰을 이용하여 새로운 접근 토큰을 발급 받아야 합니다. 토큰 발급 상세 규칙은 '4.1.4 User Access Token 및 Refresh Token 발급 기준'에 명시 되어 있습니다. #### **4.1.1 표준 응답코드**


Code	message_ko	message_en	HTTP Status Code	대상API	비고
Success	정상처리 되었습니다.	The request has been successfully completed.	200 - Success	4.4 ONE store User Access Token 삭제 요청
RequiredValueNotExist	필수값이 존재하지 않습니다. [ field1, field2, ... ]	Request parameters are required. [ field1, field2, ... ]	400 - Bad Request	공통
NoSuchData	조회된 결과값이 존재하지 않습니다.	The requested data could not be found.	404 - Not Found	단건 조회 API
ResourceNotFound	요청한 자원이 존재하지 않습니다.	The requested resource could not be found.	404 - Not Found	공통	요청한 URL 자원이 없는 경우
InternalError	정의되지 않은 오류가 발생하였습니다.	An undefined error has occurred.	500 - Internal Server Error	공통
InvalidRequest	입력값이 유효하지 않습니다. [ field1, field2, ... ]	Request parameters are invalid. [ field1, field2, ... ]	400 - Bad Request	공통
UserAccessTokenExpired	Access 토큰이 만료되었습니다.	User Access Token has expired.	401 - Unauthorized	공통	code 및 UserAccessToken 만료 처리 만료 기한 초과 시 회원 상태 변동 시 (휴면/탈퇴/통합) TStore ID 회원 패스워드 변경 시 소셜 인증 실패 시 (소셜 연동 정보 변동 - 연결 취소 등)
InvalidRefreshToken	잘못된 Refresh Token 입니다.	Invalid refresh token	400 - Bad Request	공통	grant_type : refresh_token 경우
ExpiredRefreshToken	만료된 Refresh Token 입니다.	Invalid refresh token (expired)	401 - Unauthorized	공통	grant_type : refresh_token 경우
UnauthorizedAccess	해당 API에 접근권한이 없습니다.	Not authorized to this API.	403 - Fobidden	공통
InvalidUserAccessToken	Access 토큰이 유효하지 않습니다.	User Access Token is invalid.	401 - Unauthorized	공통
InvalidAuthorizationParam	Authorization Param의 값이 유효하지 않습니다.	Authorization param is invalid.	400 - Bad Request	공통	code 올바르지 않은 code
MethodNotAllowed	지원하지 않는 HTTP Method 입니다.	HTTP method not supported.	405 - Method Not Allowed	공통
InvalidContentType	잘못된 Content Type 입니다.	The request content-type is invalid.	415 - Unsupported Media Type	공통
UserNotExist	회원 정보가 존재하지 않습니다.	User does not exist.	404 - Not Found	공통
InvalidUser	회원 정보가 유효하지 않습니다.	User information is not valid.	409 - Conflict	공통
UnsupportedResponseType		Unsupported response types: [field1]	400 - Bad Request	공통
WrongApproach		The wrong approach.	403 - Forbidden	공통

#### **4.1.2 표준 오류응답** 오류응답인 경우 표준 응답코드에 정의된 코드 및 메시지를 전달합니다. **Example** |

HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8
{
"error" : {
"code" : "NoSuchData",
"message" : "The requested data could not be found."
}
}

| | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | #### **4.1.3 client\_id와 client\_secret** client\_id와 client\_secret 값은 "개발자센터 > 상품현황 > 앱 상세 > 공통정보 > 라이선스 관리" 메뉴를 통해 확인할 수 있습니다.
#### **4.1.4 User Access Token 및 Refresh Token 발급 기준** ONE store User Access Token은 Client ID(=게임/앱)와 원스토어 사용자의 회원 ID 기준으로 발급됩니다. * grant\_type : authorization\_code * 사용자의 명시적 로그인이기 때문에 기존 token이 유효하지 않아도 신규 발급 * user\_access\_token, refresh\_token * 기존 유효한 (user\_access, refresh) token이 있는 경우 기존 value 응답 * 기존 유효한 (user\_access, refresh) token이 없는 경우 신규 발급
* grant\_type : refresh\_token * refresh\_token * 유효한 refresh\_token이 없는 경우 오류 응답 * 유효한 refresh\_token이 있는 경우 만료기한 연장(초기화: 기본 35일) * user\_access\_token * 기존 유효한 user\_access\_token이 있는 경우 기존 value 응답 * 기존 유효한 user\_access\_token이 없는 경우 신규 발급\
* 토큰 삭제 시 refresh\_token, user\_access\_token 함께 삭제 됨
### 4.2 ONE store 로그인 인증 요청 **\[ API Spec. ]**


Protocol	HTTPS
Content-Type	application/x-www-form-urlencoded
Method	GET/POST
응답 포맷	URL Redirect
Path	상용 - https://accounts.onestore.net/oauth2.0/authorize 개발 - https://qa-accounts.onestore.co.net/oauth2.0/authorize
Description	ONE store OAuth 이용 시 로그인 페이지 오류 코드 참고 : 표준 응답코드

**\[ Request ]** **Parameter**


Parameter Name	Type	Description	Required	Remarks
response_type	String	인증 과정에 대한 내부 구분값으로 'code'로 전송해야 함	Y	code
client_id	String	OAuth Client Id	Y	Android OS Application의 Package Name을 사용
redirect_uri	String	등록 시 입력한 Callback URL 값으로 URL 인코딩을 적용한 값	Y	URL 인코딩 등록을 위해 별도 요청이 필요합니다. (devhelper@onestore.co.kr)
state	String	사이트 간 요청 위조(cross-site request forgery) 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰값으로 URL 인코딩을 적용한 값을 사용	Y	URL 인코딩 개발자 측에서 생성/전달. ONE store 측은 넘겨받은 값을 그대로 리턴
scope	String	접근 허용 범위를 처리하기 위한 내부 구분값	Y	user_payment

**Header**


Parameter Name	Type	Description	Required
x-market-code	String	마켓 구분 코드 MKT_ONE: 원스토어(대한민국) MKT_GLB: 원스토어(대한민국 외)	Y

Parameter Name

Type

Description

Required

x-market-code

String

마켓 구분 코드

MKT_ONE: 원스토어(대한민국)
MKT_GLB: 원스토어(대한민국 외)

**Example** | | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | **\[ Response ]** * ONE store 로그인 인증 요청 API를 호출 했을 때 사용자가 로그인되지 않은 상태이면 로그인 화면으로 이동합니다. * 사용자 로그인 완료 후 약관 및 정보 제공 동의 등이 필요한 경우 해당 화면으로 이동합니다. * 로그인과 동의 과정이 완료되면 콜백 URL에 code값과 state 값이 URL 문자열로 전송됩니다. * code 값은 접근 토큰(User Access Token) 발급 요청에 사용됩니다.\


Element Name	Type	Description	Remarks
code	String	- 로그인 인증에 성공하면 반환받는 인증 코드 - 접근 토큰(User Access Token) 발급에 사용	length : 50 영문 대소문자 및 숫자로 구성 만료기한 5분
state	String	사이트 간 요청 위조 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰	URL 인코딩 요청 시 넘겨준 값을 그대로 리턴
error_code	String	로그인 인증에 실패하면 반환받는 에러 코드	오류 코드 참고 : 표준 응답코드
error_message	String	로그인 인증에 실패하면 반환받는 에러 메시지

**Example** |

인증 절차 완료 후

API 요청 성공시 :
API 요청 실패시 :


코드	응답 방식	발생 조건	전문 (메세지 및 화면내용)	기타 설명
RequiredValueNotExist	PAGE	필수값 누락 - response_type - client_id - state - scope - redirect_uri	Request parameters are required. [ {누락 파라미터} ]
UnsupportedResponseType	REDIRECTION	파라미터 유효성 - response_type ≠ code	{redirect_uri}?error_code=UnsupportedResponseType&error_message=Unsupported response types: [{response_type}]
InvalidRequest	PAGE	파라미터 유효성 - 미발급 client_id	Request parameters are invalid. [ client_id ]
InvalidRedirect	PAGE	파라미터 유효성 - 미등록 redirect_uri	Invalid redirect
InvalidScope	REDIRECTION	파라미터 유효성 - scope ≠ user_payment	{redirect_uri}?error_code=InvalidScope&error_message=Invalid scope	접속 후 인증 요청 시 발생
WrongApproach	PAGE	로그인 URI 직접 접근	The wrong approach.	/oauth2.0/login 직접 접근

### 4.3 ONE store User Access Token 발급 요청 **\[ API Spec. ]**


Protocol	HTTPS
Content-Type	application/x-www-form-urlencoded
Method	POST
응답 포맷	application/json
Path	상용 - https://accounts.onestore.net/oauth2.0/token
Description	ONE store User Access Token 발급 오류 코드 참고 : 표준 응답코드

**\[ Request ]** **Parameter**


Parameter Name	Type	Description	Required	Remarks
grant_type	String	접근 토큰 발급 방식에 대한 구분값	Y	'authorization_code' 'refresh_token' 그 외 발급 방식 현재 미정
client_id	String	OAuth Client Id	Y	Android OS Application의 Package Name을 사용
client_secret	String	OAuth Client Secret	Y	ONE store 개발자센터에서 발급한 Client secret 값을 사용
code	String	로그인 인증 요청 API 호출에 성공하고 응답 받은 인증코드값 (code)	N	grant_type : authorization_code 경우 필수값
refresh_token	String	User Access Token 발급 시 함께 발급받은 refresh_token 값	N	grant_type : refresh_token 경우 필수값
state	String	사이트 간 요청 위조(cross-site request forgery) 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰값으로 URL 인코딩을 적용한 값을 사용	Y	URL 인코딩 개발자 측에서 생성/전달, ONE store 측은 넘겨받은 값을 그대로 리턴 함

**Header**


Parameter Name	Type	Description	Required
x-market-code	String	마켓 구분 코드 MKT_ONE: 원스토어(대한민국) MKT_GLB: 원스토어(대한민국 외)	Y

Parameter Name

Type

Description

Required

x-market-code

String

마켓 구분 코드

MKT_ONE: 원스토어(대한민국)
MKT_GLB: 원스토어(대한민국 외)

**Example** |

POST /oauth2.0/token HTTP/1.1 Host: accounts.onestore.net Content-Type: application/x-www-form-urlencoded x-market-code:MKT\_ONE

grant\_type : authorization\_code의 경우
grant\_type=authorization\_code&
code=EIc5bFrl4RibFls1&
client\_id=client\_id\_example&
client\_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
state=9kgsGTfH4j7IyAkg

grant\_type : refresh\_token의 경우
grant\_type=refresh\_token&
refresh\_token=EIc5bFrl4RibFls1&
client\_id=client\_id\_example&
client\_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
state=9kgsGTfH4j7IyAkg

| | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | **\[ Response ]**


Element Name	Type	Description	Remarks
user_access_token	String	ONE store 접근 토큰(User Access Token)	max length : 255 만료기한 10분
refresh_token	String	User Access Token에 대한 Refresh 토큰	max length : 255 기본 만료기한 35일, 사용 시 만료기한 연장(초기화)
token_type	String	Bearer
expires_in	integer	접근 토큰의 유효 기간(초 단위)
state	String	사이트 간 요청 위조 공격을 방지하기 위해 개발자 측에서 생성한 상태 토큰	URL 인코딩 요청 시 넘겨준 값을 그대로 리턴 성공 시에만 포함됨
error	Object	error 발생 시에만 포함	오류 코드 참고 : 표준 응답코드
code	String	에러 코드
message	String	에러 메세지

**Example**


// 성공 시 `{ "user_access_token" : "f27d2c49-231d-4848-9e8c-ec9a1fef9c35", "refresh_token" : "1fe54c5f-60d1-4fbb-a412-929c84adab43", "token_type" : "Bearer", "expires_in" : 603389, "state" : "hLiDdL2uhPtsftcU" }` // 실패 시 `{ "error" : { "code" : "InvalidAuthorizationParam", "message" : "Authorization param is invalid." } }`

// 성공 시

{
  "user_access_token" : "f27d2c49-231d-4848-9e8c-ec9a1fef9c35",
  "refresh_token" : "1fe54c5f-60d1-4fbb-a412-929c84adab43",
  "token_type" : "Bearer",
  "expires_in" : 603389,
  "state" : "hLiDdL2uhPtsftcU"
}

// 실패 시

{
    "error" : {
        "code" : "InvalidAuthorizationParam",
        "message" : "Authorization param is invalid."
    }
}

**오류 유형 정리**


코드	발생 조건	전문 (json)	기타 설명
RequiredValueNotExist	필수값 누락 - grant_type - client_id - client_secret - code (선택적 필수값) - refresh_token (선택적 필수값) - state	{ "error": { "code": "RequiredValueNotExist", "message": "Request parameters are required. ({누락파라미터})" } }	- code : grant_type : authorization_code 경우 필수값 - refresh_token : grant_type : refresh_token 경우 필수값
InvalidRequest	파라미터 유효성 - grant_type ≠ (authorization_code or refresh_token)	{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ grant_type ]" } }
InvalidAuthorizationParam	파라미터 유효성 - 미발급 code	{ "error": { "code": "InvalidAuthorizationParam", "message": "Authorization param is invalid." } }
InvalidRequest	파라미터 유효성 - 미발급 client_id	{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ client_id or client_secret ]" } }
InvalidRequest	파라미터 유효성 - 미발급 client_secret	{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ client_id or client_secret ]" } }
InvalidRefreshToken	파라미터 유효성 - 미발급 refresh_token	{ "error": { "code": "InvalidRefreshToken", "message": "Invalid refresh token" } }	grant_type : refresh_token 경우
ExpiredRefreshToken	파라미터 유효성 - 만료 refresh_token	{ "error": { "code": "ExpiredRefreshToken", "message": "Invalid refresh token (expired)" } }	grant_type : refresh_token 경우

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://onestore-dev.gitbook.io/dev/tools/billing/v21/web-payment/member.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.