# Login

### Token

To make requests to the Wepin RESTful API, you must include a **Token** for authentication. Tokens for the Wepin RESTful API are generated in **JWT (JSON Web Token) format**. The API adopts an enhanced security approach using the **Access Token and Refresh Token** mechanism, a common authentication method in JWT-based systems.

{% hint style="info" %}
The **Access Token** expires 12 hours after issuance. The **Refresh Token** remains valid for 7 days and can be used to issue a new Access Token.
{% endhint %}

When a login request is made, the response includes tokens: an **accessToken** and a **refreshToken**. The detailed process for token issuance is as follows:

1. **Token Issuance During Login**
   * Access Token and Refresh Token are issued during the login process.
2. **Validate Token Before Sending an API Request**
   * If both the Access Token and Refresh Token are expired: An error is raised. Re-login is required to issue new Access and Refresh Tokens.
   * If the Access Token is expired but the Refresh Token is still valid: Use the token refresh process to verify the Refresh Token and issue a new Access Token.
   * If the Access Token is valid but the Refresh Token is expired: Re-login is required to issue new Access and Refresh Tokens.
   * If both Access Token and Refresh Token are valid: Requests can be sent without issues.
3. **Client-Side Token Validation**
   * Applications using Wepin RESTful API should verify token validity before sending a request. If the token is valid, proceed with the request.
4. **Handle Token Expiry During Requests**
   * If the token validity is not verified before the API request and an HTTP Status Code 401 (Unauthorized) is returned, the client should refresh the token before retrying the request.

#### Request Header

Below are the required values for the **Request Header** when using the Wepin SDK API:

<table><thead><tr><th width="182">Name</th><th width="181">Value</th><th>Description</th></tr></thead><tbody><tr><td>X-API-KEY</td><td>${APP_KEY}</td><td>The App Key assigned during app registration</td></tr><tr><td>X-API-DOMAIN</td><td>${APP_DOMAIN}</td><td>The base domain, package name, or bundle ID registered when creating the app</td></tr><tr><td>Authorization</td><td>Bearer {token}</td><td>Bearer {token} where {token} is the Access Token received after Wepin login</td></tr><tr><td>X-SDK-TYPE</td><td>{platform}_rest_api</td><td>The platform using the RESTful API (e.g., android, ios, web). Example: web_res_api</td></tr><tr><td>Content-Type</td><td>application/json</td><td></td></tr></tbody></table>

#### Status Code

<table><thead><tr><th width="260">Code</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>Success. JSON object included in the response.</td></tr><tr><td>400</td><td>Invalid data sent.</td></tr><tr><td>401</td><td>Token expired.</td></tr><tr><td>403</td><td>App Key error.</td></tr><tr><td>404</td><td>Not found.</td></tr><tr><td>500</td><td>Server internal error.</td></tr></tbody></table>

#### Error Response

<table><thead><tr><th width="162">Name</th><th width="180">Type</th><th>Description</th></tr></thead><tbody><tr><td>message</td><td>String</td><td>Error message</td></tr><tr><td>code</td><td>Integer</td><td>Error code value</td></tr><tr><td>data</td><td>Object</td><td>Error detail data</td></tr></tbody></table>

### Check App Information

Check the validity of the issued App Key and confirm whether the registered app information is correct.

```http
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**

<table><thead><tr><th width="148">Name</th><th width="104">Type</th><th width="377">Description</th><th>Required</th></tr></thead><tbody><tr><td>platform</td><td>Integer</td><td><code>1</code>: web<br><code>2</code>: android<br><code>3</code> : ios</td><td>O</td></tr><tr><td>withNetwork</td><td>Boolean</td><td><code>true</code>: Returns the network information used by the app registered in the Workspace.<br><code>false</code>: Does not return the network information used by the app registered in the Workspace. Default value.</td><td>X</td></tr></tbody></table>

#### Response

**Success Response**

| Name    | Type    | Description                                                   |
| ------- | ------- | ------------------------------------------------------------- |
| stage   | Integer | <p><code>1</code>: development<br><code>2</code>: product</p> |
| appInfo | Object  | App information(`appinfo`)                                    |

* `appInfo`
  * `id` : App ID
  * `assets` *array of object*
    * `coinId` *integer*
      * Network coin ID used by the app
    * `tokens` *integer\[]*
      * List of FT (Fungible Token) IDs used by the app

***

### **Login** <a href="#login" id="login"></a>

To use the Wepin Wallet, you must log in. Wepin supports social login and email login through Firebase. To view the list of social login options supported by Wepin, please refer to the [Social Login Provider page](/en/login/social-login-auth-providers.md).

{% hint style="info" %}
Wepin provides login libraries tailored to various development environments. For a list of login libraries by platform, see the [API Overview page](/en/api/overview.md).
{% endhint %}

Perform Wepin login using the token obtained from the Firebase login result.

```http
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**

<table><thead><tr><th width="151">Name</th><th width="115">Type</th><th width="342">Description</th><th>Required</th></tr></thead><tbody><tr><td>idToken</td><td>String</td><td>(Using Wepin Login Library) Token value obtained from firebase login result</td><td>O</td></tr></tbody></table>

#### **Response**

<table><thead><tr><th width="186">Name</th><th width="173">Type</th><th>Description</th></tr></thead><tbody><tr><td>loginStatus</td><td>String</td><td><code>pinRequired</code>: If this is the user's first login to Wepin, they must register with Wepin and create a new wallet. Therefore, the user needs to set a PIN required for wallet creation.<br><code>registerRequired</code>: If the user already has a Wepin wallet but is using the app for the first time, the user's Wepin wallet must register the app. Therefore, user PIN authentication for the existing wallet is required.<br><code>complete</code>: Indicates that the user login has been successfully completed.</td></tr><tr><td>walletId</td><td>string (optional)</td><td>The user's wallet ID. If the wallet already exists (when <code>loginStatus</code> is <code>registerRequired</code> or <code>complete</code>), the <code>walletId</code> will be returned.</td></tr><tr><td>token</td><td>Object</td><td>When the Wepin login is successfully completed, a token is returned.</td></tr><tr><td>userInfo</td><td>UserInfo (Object)</td><td>User information for the completed login. It is returned only when loginStatus is complete. (userInfo)</td></tr></tbody></table>

* `token`
  * `access` *String*
    * Access Token (Encoded JWT Token)
  * `refresh` *String*
    * Refresh Token (Encoded JWT Token)

* `userInfo`
  * `userId` *String*
    * User Id
  * `email` *String*
    * User e-mail
  * `name` *String*
    * User's name
  * `locale` *String*
    * Language set by the user
  * `currency` *String*
    * Currency set by the user
  * `lastAccessDevice` *String*
    * Last connected device
  * `lastSessionIp` *String*
    * Last connected IP
  * `userJoinStage` *Integer*
    * User registration stage (Not used when directly calling REST API)
    * `3`: Registration completed
  * `profileImage` *String*
    * URL of the user's profile image
  * `userState` *Integer*
    * User status
    * `1`: active
    * `2`: deleted
  * `user2FA` *Integer*
    * 2FA activation status
    * `0` : Created but not yet authenticated - 2FA not available
    * `1` : Registration completed
    * `2`: 2FA recovery code verification completed

*Example*

```json
{
    "loginStatus": "complete",
    "userInfo": {
        "email": "sample-user@wepin.io",
        "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
    }
}
```

***

### Logout

Performs user logout. Used together with Firebase logout and the `logout` function of the Wepin Login Library.

```http
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**

<table><thead><tr><th width="149">Name</th><th width="103">Type</th><th width="364">Description</th><th>Required</th></tr></thead><tbody><tr><td>userId</td><td>String</td><td>The <code>userId</code> from the <code>userInfo</code> received during the <a href="#login">login</a> process.</td><td>O</td></tr></tbody></table>

#### Response

**Success Response**

Returns an empty object.

```
{}
```

***

### Token Reissuance <a href="#token-reissuance" id="token-reissuance"></a>

If the issued Access Token has expired but the Refresh Token is still valid, a new Access Token must be reissued.

```http
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**

<table data-header-hidden><thead><tr><th width="173"></th><th width="118"></th><th width="361"></th><th></th></tr></thead><tbody><tr><td><strong>Name</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td><td><strong>Required</strong></td></tr><tr><td>userId</td><td>String</td><td>The <code>userId</code> from the <code>userInfo</code> received during the <a href="#login">login</a> process.</td><td>O</td></tr><tr><td>refresh_token</td><td>String</td><td>Refresh Token received during the login process (token)</td><td>O</td></tr></tbody></table>

#### Response

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | New Access Token |

***

### Agreeing to Terms of Service <a href="#agreeing-to-terms-of-service" id="agreeing-to-terms-of-service"></a>

When logging into the Wepin wallet, users must agree to the wallet's terms of service. After successfully [login](#login), the user's agreement status is updated on the Wepin backend server.

```http
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**

<table><thead><tr><th width="163">Name</th><th width="95">Type</th><th width="395">Description</th><th>Required</th></tr></thead><tbody><tr><td>termsAccepted</td><td>Object</td><td>The terms agreed upon by the user.<br>If additional types of terms are introduced, new properties will be added.<br>Once the value of a property is set to <code>true</code>, it cannot revert to <code>false</code>.</td><td>O</td></tr></tbody></table>

* `termsAccepted`
  * `termsOfService` *Boolean*
    * Agreement to the Terms of Service
  * `privacyPolicy` *Boolean*
    * Agreement to the Privacy Policy
* Agreement to Wepin Wallet Service Terms
  * Terms of Service: <https://delivery.wepin.io/service/terms/en.html>
  * Privacy Policy: <https://delivery.wepin.io/service/privacy/en.html>

#### Response

The content matches the body of the Request.

<table><thead><tr><th width="162">Name</th><th width="89">Type</th><th>Description</th></tr></thead><tbody><tr><td>termsAccepted</td><td>Object</td><td>The terms agreed upon by the user.<br>If additional types of terms are introduced, new properties will be added.<br>Once the value of a property is set to <code>true</code>, it cannot revert to <code>false</code>.</td></tr></tbody></table>

## Get Terms of Service Agreement Status

Use the API to get the user's agreement status for the terms of service.

#### Request

**Parameter**

#### Response

<table><thead><tr><th width="161">Name</th><th width="89">Type</th><th width="415">Description</th><th>Required</th></tr></thead><tbody><tr><td>termsAccepted</td><td>Object</td><td>Terms agreed upon by the user.<br>If additional types of terms are introduced, new properties will be added.<br>Once the value of a property is set to <code>true</code>, it cannot revert to <code>false</code>.</td><td>O</td></tr></tbody></table>


---

# Agent Instructions: 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:

```
GET https://docs.wepin.io/en/api/login.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.