Membership Authentication

1.Overview

When servicing a Windows app in the EXE format, integration with Purchases on the Web is required. Since membership authentication (login) is necessary for Purchases on the Web integration, this specification is provided.

  • The Payment Server API uses the OAuth Token (hereinafter referred to as User Access Token) issued during membership authentication (login).

  • OAuth authentication is supported to prevent the need for membership authentication (login) for every payment.

2.Precautions

A 403 error will occur if you attempt Google OAuth login in an Embedded Browser (WebView) without applying the Google SDK. You can prevent the 403 error using the following methods:

  • Attempt login in a new window instead of an Embedded Browser.

  • Modify the User-Agent information to make it recognized as a web browser instead of an Embedded Browser.

3.Membership Authentication Flow

3.1 Conceptual View

3.2 Logical API ↔ Physical API Specification Mapping

The physical API specifications mapped to the logical APIs listed in the Conceptual View are as follows.

No
Flow
Logical API
Physical API (Integration Specifications)

1

Membership Authentication

  1. Login UI Request

4.2 ONE store Login Authentication Request

2

Membership Authentication

  1. Issuance of ONEstore UserAccessToken

4.3 ONE store User Access Token Issuance Request

4. ONE store Membership Authentication

4.1 Overview of ONE store Login API

The ONE store Login API consists of the following:

  • ONE store Login Authentication Request API

  • User Access Token Issuance/Deletion Request API

The ONE store Login Authentication Request API is an API that displays the ONE store login screen on the developer's service web. When the user successfully completes ONE store membership authentication, the temporary code (code) received from the API is used to call the User Access Token Issuance Request API.

The User Access Token obtained through the issuance request API is used to call various Server APIs.

The User Access Token has a shorter expiration period compared to the Refresh Token, and when it expires, a new User Access Token must be issued using the Refresh Token.

The detailed token issuance rules are specified in "4.1.4 User Access Token and Refresh Token Issuance Criteria."

4.1.1 Standard Response Codes

Code

message_ko

message_en

HTTP Status Code

Target API

Remarks

Success

정상처리 되었습니다.

The request has been successfully completed.

200 - Success

4.4 ONE store User Access Token Deletion Request

RequiredValueNotExist

필수값이 존재하지 않습니다. [ field1, field2, ... ]

Request parameters are required. [ field1, field2, ... ]

400 - Bad Request

Common

NoSuchData

조회된 결과값이 존재하지 않습니다.

The requested data could not be found.

404 - Not Found

Single Lookup AP

ResourceNotFound

요청한 자원이 존재하지 않습니다.

The requested resource could not be found.

404 - Not Found

Common

When the requested URL resource does not exist

InternalError

정의되지 않은 오류가 발생하였습니다.

An undefined error has occurred.

500 - Internal Server Error

Common

InvalidRequest

입력값이 유효하지 않습니다. [ field1, field2, ... ]

Request parameters are invalid. [ field1, field2, ... ]

400 - Bad Request

Common

UserAccessTokenExpired

Access 토큰이 만료되었습니다.

User Access Token has expired.

401 - Unauthorized

Common

Code and UserAccessToken Expiration Processing

  • When the expiration period is exceeded

  • When the membership status changes (Dormant/Withdrawn/Merged)

  • When the TStore ID member password is changed

  • When social authentication fails (e.g., changes in social integration information, such as unlinking)

InvalidRefreshToken

잘못된 Refresh Token 입니다.

Invalid refresh token

400 - Bad Request

Common

grant_type: refresh_token case

ExpiredRefreshToken

만료된 Refresh Token 입니다.

Invalid refresh token (expired)

401 - Unauthorized

Common

grant_type: refresh_token case

UnauthorizedAccess

해당 API에 접근권한이 없습니다.

Not authorized to this API.

403 - Fobidden

Common

InvalidUserAccessToken

Access 토큰이 유효하지 않습니다.

User Access Token is invalid.

401 - Unauthorized

Common

InvalidAuthorizationParam

Authorization Param의 값이 유효하지 않습니다.

Authorization param is invalid.

400 - Bad Request

Common

  • code

  • Invalid code

MethodNotAllowed

지원하지 않는 HTTP Method 입니다.

HTTP method not supported.

405 - Method Not Allowed

Common

InvalidContentType

잘못된 Content Type 입니다.

The request content-type is invalid.

415 - Unsupported Media Type

Common

UserNotExist

회원 정보가 존재하지 않습니다.

User does not exist.

404 - Not Found

Common

InvalidUser

회원 정보가 유효하지 않습니다.

User information is not valid.

409 - Conflict

Common

UnsupportedResponseType

Unsupported response types: [field1]

400 - Bad Request

Common

WrongApproach

The wrong approach.

403 - Forbidden

Common

4.1.2 Standard Error Response

In the case of an error response, the predefined code and message from the standard response codes are returned.

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

The client_id and client_secret values can be found in "Developer Center > Application > App Detail > Common Info > Settings for Licensing".

4.1.4 User Access Token and Refresh Token Issuance Criteria

The ONE store User Access Token is issued based on the Client ID (Game/App) and the ONE store user’s Membership ID.

  • grant_type : authorization_code

    • Since this involves explicit user login, a new token is issued even if the existing token is still valid.

    • user_access_token, refresh_token

      • If valid (user_access_token, refresh_token) already exist, the existing values are returned.

      • If no valid (user_access_token, refresh_token) exist, new tokens are issued.

  • grant_type : refresh_token

    • refresh_token

      • If no valid refresh_token exists, an error response is returned.

      • If a valid refresh_token exists, the expiration period is extended (reset to the default 35 days).

    • user_access_token

      • If a valid user_access_token exists, the existing value is returned.

      • If no valid user_access_token exists, a new one is issued.

  • When a token is deleted, both refresh_token and user_access_token are deleted together.

4.2 ONE store Login Authentication Request

[ API Spec. ]

Protocol

HTTPS

Content-Type

application/x-www-form-urlencoded

Method

GET/POST

Response Format

URL Redirect

Path

Production

- https://accounts.onestore.net/oauth2.0/authorize

Development

- https://qa-accounts.onestore.co.net/oauth2.0/authorize

Description

Login Page When Using ONE store OAuth

Error Codes Reference: Standard Response Codes

[ Request ]

Parameter

Parameter Name

Type

Description

Required

Remarks

response_type

String

The internal identifier for the authentication process must be sent as 'code'.

Y

  • code

client_id

String

OAuth Client Id

Y

Use the Package Name of the Android OS Application.

redirect_uri

String

The value is URL-encoded and sent to the Callback URL registered during registration.

Y

UURL Encoding

state

String

To prevent cross-site request forgery attacks, the URL-encoded value is used as a state token generated by the developer.

Y

  • URL Encoding

  • Generated and passed by the developer. ONE store returns the received value as is.

scope

String

It serves as an internal identifier to handle the scope of access permissions.

Y

  • user_payment

Header

Parameter Name

Type

Description

Required

x-market-code

String

Market Classification Code

  • MKT_ONE: ONE store (South Korea)

  • MKT_GLB: ONE store (other than South Korea)

Y

Example

https://accounts.onestore.net/oauth2.0/authorize?response_type=code&client_id=client_id_example&redirect_uri=http%3A%2F%2Fservice.redirect.url%2Fsubpath&state=hLiDdL2uhPtsftcU&scope=user_payment

[ Response ]

  • When the ONE store Login Authentication Request API is called and the user is not logged in, they will be redirected to the login screen.

  • After the user completes the login, if agreement to terms and information provision is required, they will be redirected to the corresponding screen.

  • Once the login and consent process are completed, the code value and state value are sent as URL parameters to the callback URL.

  • The code value is used for the User Access Token issuance request.

Element Name

Type

Description

Remarks

code

String

- Authentication code returned upon successful login authentication

- Used for User Access Token issuance

  • length : 50

  • Consists of uppercase and lowercase English letters and numbers

  • Expiration period: 5 minutes

state

String

State token generated by the developer to prevent cross-site request forgery (CSRF) attacks

  • URL encoding

  • Returns the exact value passed in the request

error_code

String

Error code returned upon login authentication failure

Error codes reference: Standard Response Codes

error_message

String

Error message returned upon login authentication failure

Example

After completing the authentication process:

  • If the API request is successful:

    • http://CallbackURL?code={code_value}&state={state_value}

  • If the API request fails:

    • http://CallbackURL?state={state_value}&error_code={error_code_value}&error_message={error_message}

Error Type Summary

Code

Response Method

Occurrence Conditions

Details (Message and Screen Content)

Additional Explanation

RequiredValueNotExist

PAGE

Missing Required Values - response_type - client_id - state - scope - redirect_uri

Request parameters are required. [ {Missing Parameter} ]

UnsupportedResponseType

REDIRECTION

Parameter Validity - response_type ≠ code

{redirect_uri}?error_code=UnsupportedResponseType&error_message=Unsupported response types: [{response_type}]

InvalidRequest

PAGE

Parameter Validity - Unissued client_id

Request parameters are invalid. [ client_id ]

InvalidRedirect

PAGE

Parameter Validity - Unregistered redirect_uri

Invalid redirect

InvalidScope

REDIRECTION

Parameter Validity - scope ≠ user_payment

{redirect_uri}?error_code=InvalidScope&error_message=Invalid scope

Occurs when an authentication request is made after access

WrongApproach

PAGE

Direct Access to Login URI

The wrong approach.

Direct access to /oauth2.0/login

4.3 ONE store User Access Token Issuance Request

[ API Spec. ]

Protocol

HTTPS

Content-Type

application/x-www-form-urlencoded

Method

POST

Response Format

application/json

Path

Production

- https://accounts.onestore.net/oauth2.0/token

Development

- https://qa-accounts.onestore.net/oauth2.0/token

Description

  • ONE store User Access Token Issuance

[ Request ]

Parameter

Parameter Name

Type

Description

Required

Remarks

grant_type

String

Classification value for the access token issuance method

Y

  • 'authorization_code'

  • 'refresh_token'

  • Other issuance methods are currently undecided

client_id

String

OAuth Client Id

Y

Uses the Package Name of the Android OS Application

client_secret

String

OAuth Client Secret

Y

Uses the Client secret value issued by the ONE store Developer Center

code

String

Authentication code (code) received in response after successfully calling the login authentication request API

N

grant_type : Required value for authorization_code

refresh_token

String

Urefresh_token value issued together when obtaining the User Access Token

N

grant_type : Required value for refresh_token

state

String

To prevent cross-site request forgery attacks, the URL-encoded value is used as a state token generated by the developer.

Y

  • URL encoding

  • Generated and passed by the developer. ONE store returns the received value as is.

Header

Parameter Name

Type

Description

Required

x-market-code

String

Market Classification Code

  • MKT_ONE: ONE store (South Korea)

  • MKT_GLB: ONE store (other than South Korea)

Y

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 : In the case of authorization_code grant_type=authorization_code& code=EIc5bFrl4RibFls1& client_id=client_id_example& client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe& state=9kgsGTfH4j7IyAkg

grant_type : In the case of 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 Access Token (User Access Token)

  • max length : 255

  • 만료기한 10분

refresh_token

String

Refresh Token for the User Access Token

  • max length : 255

  • 기본 만료기한 35일, 사용 시 만료기한 연장(초기화)

token_type

String

Bearer

expires_in

integer

Expiration time of the Access Token (in seconds)

state

String

State token generated by the developer to prevent cross-site request forgery attacks

  • URL Encoding

  • Returns the exact value passed in the request

  • Included only on success

error {

Object

Included only when an error occurs

Error Codes Reference: Standard Response Codes

code

String

Error Code

message

String

Error Message

}

Example

// On Success

{

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

// On Failure

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

Error Type Summary

Code

Occurrence Conditions

Details (JSON)

Additional Explanation

RequiredValueNotExist

Missing Required Values - grant_type - client_id - client_secret - code (Optional Required Values) - refresh_token (Optional Required Values) - state

{ "error": { "code": "RequiredValueNotExist", "message": "Request parameters are required. ({Missing Parameter})" } }

- code: Required value when grant_type is authorization_code

- refresh_token: Required value when grant_type is refresh_token

InvalidRequest

Parameter Validity - grant_type ≠ (authorization_code or refresh_token)

{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ grant_type ]" } }

InvalidAuthorizationParam

Parameter Validity - Unissued code

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

InvalidRequest

Parameter Validity - Unissued client_id

{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ client_id or client_secret ]" } }

InvalidRequest

Parameter Validity - Unissued client_secret

{ "error": { "code": "InvalidRequest", "message": "Request parameters are invalid. [ client_id or client_secret ]" } }

InvalidRefreshToken

Parameter Validity - Unissued refresh_token

{ "error": { "code": "InvalidRefreshToken", "message": "Invalid refresh token" } }

grant_type : In the case of refresh_token

ExpiredRefreshToken

Parameter Validity - Expired refresh_token

{ "error": { "code": "ExpiredRefreshToken", "message": "Invalid refresh token (expired)" } }

grant_type : In the case of refresh_token

Last updated