로그인

위핀 RESTful API는 아래와 같이 인증이 필요합니다.

토큰

위핀 RESTful API 요청 시, Token을 추가하여 인증을 수행해야 합니다. 위핀 RESTful API의 토큰은 JWT 토큰 포맷으로 생성 됩니다. 기본 JWT 방식의 인증(보안) 강화 방식인 Access Token & Refresh Token 인증 방식을 채택해서 사용합니다.

Access Token은 발급 후 12시간 후 만료됩니다. Refresh Token은 7일 동안 유효하며, 이를 통해 새로운 Access Token을 발급 받을 수 있습니다.

로그인 요청을 보내면 Response에 토큰이 반환됩니다. 여기에는 accessToken과 refreshToken 토큰이 포함되어 있습니다. 자세한 토큰 발급 절차는 아래와 같습니다.

1. 로그인 과정에서 Access Token과 Refresh Token 을 발급 받습니다.

2. 이후 API Request를 보내기 전에 토큰의 유효성을 검증합니다.

   • Access Token과 Refresh Token 모두 만료된 경우: 에러 발생. 다시 로그인을 수행해서 새로운 Access Token과 Refresh Token을 발급 받습니다.

   • Access Token은 만료되었지만 Refresh Token은 유효한 경우: 토큰 재발급 받기를 통해서 Refresh Token을 검증하여 Access Token 을 재발급 받습니다.

   • Access Token은 유효하지만 Refresh Token은 만료된 경우: 다시 로그인을 수행하여 새로운 Access Token과 Refresh Token을 발급 받습니다.

   • Access Token과 Refresh Token 모두 유효한 경우: 정상적으로 Request를 보낼 수 있습니다.

3. 위핀 RESTful API를 사용하는 클라이언트 어플리케이션은 토큰의 유효 시간을 확인 후, 토큰이 유효한 경우에만 Request를 수행합니다.

4. 또는 토큰 유효성 검증 없이 API Request를 전송하고, HTTP Status 코드 401을 받으면 토큰을 재발급 받습니다.

Request 헤더

위핀 SDK API의 Request 헤더 값입니다.

Name	Value	Description
X-API-KEY	${APP_KEY}	앱 등록 시 할당 받은 App Key 값
X-API-DOMAIN	${APP_DOMAIN}	앱 생성 시 등록한 기본 도메인 또는 패키지 이름 또는 bundle ID
Authorization	Bearer {token}	{token}은 위핀 로그인 후 받은 Access Token
X-SDK-TYPE	{platform}_rest_api	RESTful API를 사용하는 플랫폼 <android | ios | web> . e.g) web_res_api
Content-Type	application/json

Status Code

Code	Description
200	성공. Response에 JSON 객체를 포함.
400	잘못된 데이터 전송
401	토큰 만료
403	App Key 오류
404	Not Found
500	서버 Internal 오류

Error Response

Name	Type	Description
message	String	에러 메시지
code	Integer	에러 코드 값
data	Object	에러 상세 데이터

---

앱 정보 확인하기

앱 등록 후 발급 받은 App Key 검증 및 등록한 앱에 대한 정보가 맞는지 확인합니다.

GET /v1/app/info HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json

Request

Parameter

Name	Type	Description	Required
platform	Integer	1: web 2: android 3 : ios	O
withNetwork	Boolean	true: 워크스페이스에 등록한 앱이 사용할 네트워크 정보를 반환함. false: 워크스페이스에 등록한 앱이 사용할 네트워크 정보 반환 하지 않음. default 값.	X

Response

Success Response

Name	Type	Description
stage	Integer	1: development 2: product
appInfo	Object	앱 정보(appinfo)

• appInfo

  • id : App ID

  • assets array of object

    • coinId integer

      • 앱에서 사용하는 네트워크 코인 ID

    • tokens integer[]

      • 앱에서 사용하는 FT(Fungible Token) ID List

---

로그인

위핀 지갑을 사용하기 위해서 로그인을 해야 합니다. 위핀은 Firebase를 이용한 소셜 로그인 및 이메일 로그인을 지원하고 있습니다. 위핀에서 지원하는 소셜 로그인 목록을 확인하려면 소셜 로그인 인증 프로바이더 페이지를 참고하세요.

위핀은 다양한 개발 환경에 맞게 로그인 라이브러리를 제공하고 있습니다. 플랫폼에 따른 로그인 라이브러리 목록은 API의 개요 페이지를 참고하세요.

Firebase 로그인 결과로 얻은 토큰을 이용하여 위핀 로그인을 수행합니다.

POST /v1/user/login HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json

{
	"idToken": "abc12..22"
}

Request

Parameter

Name	Type	Description	Required
idToken	String	(위핀 로그인 라이브러리를 이용하여) Firebase 로그인 결과 얻은 토큰 값	O

Response

Name	Type	Description
loginStatus	String	pinRequired: 위핀 최초 로그인인 경우, 위핀 회원 가입과 동시에 새로운 지갑을 생성해야 합니다. 따라서 지갑 생성에 필요한 사용자 PIN 등록이 필요합니다. registerRequired: 사용자가 이미 위핀 지갑을 가지고 있지만 해당 앱을 처음 사용하는 경우, 사용자의 위핀지갑에 해당 앱 등록을 해야 합니다. 따라서 기존에 생성한 사용자 지갑의 사용자 PIN 인증이 필요합니다. complete: 사용자 로그인이 완료 되었음을 의미합니다.
walletId	string (optional)	사용자 지갑 ID. 지갑이 이미 생성되어 있는 경우(loginStatus 가 registerRequired, complete 인 경우) walletId 가 반환됩니다.
token	Object	위핀에 정상적으로 로그인이 완료되면 token 이 반환됩니다.
userInfo	UserInfo (Object)	로그인 완료된 경우의 사용자 정보입니다. loginStatus가 complete 인 경우에만 반환 됩니다. (userInfo)

• token

  • access String

    • Access Token (인코딩 된 JWT 토큰)

  • refresh String

    • Refresh Token (인코딩 된 JWT 토큰)

• userInfo

  • userId String

    • 사용자 Id

  • email String

    • 사용자의 e-mail

  • name String

    • 사용자의 이름

  • locale String

    • 사용자가 설정해 놓은 언어

  • currency String

    • 사용자가 설정해 놓은 통화

  • lastAccessDevice String

    • 마지막 접속 기기

  • lastSessionIp String

    • 마지막 접속 IP

  • userJoinStage Integer

    • 사용자 가입 단계. (REST API를 직접 호출 하는 경우 사용하지 않음)

    • 3: 가입 완료

  • profileImage String

    • 사용자의 프로필 이미지 URL

  • userState Integer

    • 사용자 상태

    • 1: active

    • 2: deleted

  • user2FA Integer

    • 2FA 활성화 여부

    • 0 : 생성은 됐지만 인증이 되지 않은 상태 - 2FA 사용 불가

    • 1 : 등록 완료 상태

    • 2: 2FA 복구 코드 검증 완료된 상태

Example

{
    "loginStatus": "complete",
    "userInfo": {
        "email": "[e-mail]",
        "name": "Sample User Name",
        "locale": "ko",
        "currency": "KRW",
        "lastAccessDevice": "Windows 10 Chrome 112.0.0.0",
        "lastSessionIP": "xxx.xxx.xxx.xxx",
        "userJoinStage": 3,
        "profileImage": "<https://profile.wepin.io/user-1>",
        "userState": 1,
        "use2FA": 2
    }
}

---

로그아웃

사용자 로그아웃을 수행합니다. Firebase 로그아웃과 위핀 로그인 라이브러리의 logout 함수와 함께 사용됩니다.

POST /v1/user/{userId}/logout HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}

Request

Parameter

Name	Type	Description	Required
userId	String	로그인 과정에서 받은 userInfo의 userId.	O

Response

Success Response

비어 있는 Object를 반환 합니다.

{}

---

토큰 재발급 받기

발급 받은 Access Token이 만료되고 Refresh Token은 유효한 경우에, 새로운 Access Token을 재발급 받아야 합니다.

GET /v1/user/access-token?userId={userId}&refresh_token={refresh_token} HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}

Request

Parameter

Name	Type	Description	Required
userId	String	로그인 과정에서 받은 userInfo의 userId.	O
refresh_token	String	로그인 과정에서 받은 Refresh Token. (token)	O

Response

Name	Type	Description
token	String	새로운 Access Token

---

이용 약관 동의하기

위핀 지갑 로그인과 동시에 사용자는 지갑 이용 약관에 동의 해야 합니다. 로그인에 성공한 후 이용 약관 동의 여부를 위핀 백엔드 서버에 업데이트 합니다.

PATCH /v1/user/{userId}/terms-accepted HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}

{
	"termsAccepted": {
		"termsOfService": true 
		"privacyPolicy": true,
	}
}

Request

Parameter

Name	Type	Description	Required
termsAccepted	Object	사용자가 동의한 약관 입니다. 약관의 종류가 늘어나는 경우 property가 추가됩니다. 각 property의 값이 true로 변경되면 이후에 다시 false가 될 수 없습니다.	O

• termsAccepted

  • termsOfService Boolean

    • 서비스 이용 약관 동의 여부

  • privacyPolicy Boolean

    • 개인정보 처리 방침 동의 여부

• 위핀 지갑 서비스 약관

  • 이용약관: https://delivery.wepin.io/service/terms/ko.html

  • 개인정보처리방침: https://delivery.wepin.io/service/privacy/ko.html

Response

Request의 body와 동일합니다.

Name	Type	Description
termsAccepted	Object	사용자가 동의한 약관 입니다. 약관의 종류가 늘어나는 경우 property가 추가됩니다. 각 property의 값이 true로 변경되면 이후에 다시 false가 될 수 없습니다.

이용 약관 동의 여부 가져오기

사용자의 이용 약관 동의 여부를 가져 올 수 있습니다.

GET /v1/terms-accepted HTTP/1.1
Host: sdk.wepin.io
X-API-KEY: ${APP_KEY}
X-API-DOMAIN: {APP_DOMAIN}
X-SDK-TYPE: {platform}_rest_api
Content-Type: application/json
Authorization: Bearer ${access_token}

Request

Parameter

Response

Name	Type	Description	Required
termsAccepted	Object	사용자가 동의한 약관 입니다. 약관의 종류가 늘어나는 경우 property가 추가가 됩니다. 각 property의 값이 true로 변경되면 이후에 다시 false가 될 수 없습니다.	O